# Introduction to Kleros Overview of the Kleros Decentralized Dispute Resolution Protocol ## What is Kleros? {% embed url="" %} Kleros is a decentralized dispute resolution 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. ### Kleros Services ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-118673393af0f3b4df667d5e0525ae7478a54069%2FKleros%20products.png?alt=media) # Kleros FAQ ❓ Frequently Asked Questions about Kleros ## General ### Can you really trust a decision made by a bunch of anonymous people on the Internet? Satoshi Nakamoto taught us that a number of anonymous computers who do not trust each can still reach consensus, provided incentives are correctly structured. Kleros extends this principle to human decision-making. A number of anonymous jurors who do not trust each other can reach consensus on a right decision, provided incentives are correctly structured. Since decisions made in Kleros affect the allocation of resources, there is an incentive for parties to try to bribe or intimidate the tribunal. Pseudonymity is intended to protect jurors from bribing attempts, intimidation, and retaliation. It favors their functional independence (ability to freely give their judgement). It also simplifies the process of users becoming jurors and avoids the costs of identity verification. By providing a secure environment and simplifying the selection process, Kleros greatly enlarges the pool of potential jurors. This results in lower arbitration costs and the democratization of access to justice. To learn more about the incentive system, read our white paper. ### How long has Kleros been operating? Kleros Court has been live since 2018 on Ethereum mainnet, and it has handled and ruled on more than a thousand different cases and has a community of more than 760 active jurors staking in 23 different courts (Source: [KlerosBoard](http://klerosboard.com)). Kleros Court has ruled fairly on several controversial cases where millions of dollars were at stake (cf. [Famous Kleros Cases](https://kleros.gitbook.io/docs/products/court/famous-kleros-cases)). It is trusted as an unbiased and transparent arbitration layer by multiple Dapps of the ecosystem in different fields (Prediction Markets, Insurance, DEX, Sybil-Resistance, Marketplaces,... check all those integrations [here](https://kleros.gitbook.io/docs/integrations/live-and-upcoming-integrations)). ### What is the PNK token supply? The current total supply is 764,626,704 PNK. The supply can only be modified by the Kleros community through a DAO governance vote. ### Does a party who wants to have a case adjudicated need to hold PNK? No, only jurors will need PNK in order to be drawn. Parties don’t even need to know what the Kleros token is. ### Is the identity of jurors revealed? Since decisions made in Kleros affect the allocation of resources, there is an incentive for parties to try to bribe or intimidate the tribunal. Anonymity is intended to protect jurors from intimidation and retaliation. It also simplifies the process of users becoming jurors and avoids the costs of identity verification. By providing a secure environment and simplifying the selection process, Kleros greatly enlarges the pool of potential jurors. This results in lower arbitration costs and the democratization of access to justice. ### What is Kleros token allocation? Team Members: 18% First Round of Token Sale: 16% Airdrop: 4% Subsequent Rounds and Juror Incentive Program: 50% Kleros Cooperative Development Reserve: 12% ### Could Kleros become a platform used by mainstream online retailers such as eBay or Amazon? Yes, by adopting Kleros, any mainstream e-commerce platform could enjoy a fast, affordable, and transparent dispute resolution method. If you want to learn more, watch this talk ["When Decentralized Protocols Meet the Real World"](https://youtu.be/ssdgdV_fngI) or contact us. ### Is Kleros a court where rich people have more rights than ordinary folks (because appeals are more affordable for the rich)? / How can I expect fairness from a court where whales have staked a lot of PNK? Anyone can appeal a dispute ruling in Kleros. Most of the time both sides will be asked to contribute fees for the next round of voting to ensure jurors are rewarded and that the winning side is reimbursed of its paid fees. This appeal system ensures that the final decision of jurors will always converge to the truth and that jurors in initial rounds of voting vote coherently from the start not to be penalized. This usually leads to some critics saying that one of the parties with much greater resources than the other can always win a case. We have made a number of design choices regarding the structure of the appeal fee process in order for Kleros to provide just outcomes even in this situation: 1. Appeal fees can be “crowdfunded.” Namely, anyone can contribute a portion of either sides' appeal fees, potentially with many small contributions adding up to cover the whole fee. 2. Crowdfunders who pay part of the fees of the side that ultimately wins are financially rewarded. People are thus incentivized to look at current appealed cases to spot obvious incorrect rulings and help crowdfund the other side to earn all or part of the rewards. This has been proven effective to deter "rich" parties from trying to win just by appealing several times and it can make them lose a lot of money if they are malicious. Learn more about it [here](https://blog.kleros.io/kleros-decentralized-token-listing-appeal-fees/). ### Can't someone just buy a lot of Kleros tokens and 51% attack the Kleros Court? In order for a "whale" attacker to flood the juror pool and try to "control the court", they would need to buy enough PNK so that they are selected enough times to be a juror for the same case in order to change the outcome. Generally, this means that the attacks need 51% of the total staked tokens. An attacker may get lucky in rare circumstances and be selected for two of three juror spots with only a minority of the PNK. However, in order to maintain the attack through the appeal process, it would need to be selected for the majority of the juror spots on larger and larger juries, which will only be possible if the attacker actually has a majority of the PNK. Hence, substantial economic resources in the order of hundreds of millions of dollars would be required to perform a 51% attack.\ \ ***If a "whale" tries to buy 51% of all staked PNK:*** The PNK market liquidity will dry up. As the attacker buys PNK, it will start to become scarce and each additional PNK will cost more and more. The attacker may not even be able to find 51% of PNK for sale on the open market at any given time and it will progressively cost so much that the attack would not be economically viable.\ \ ***If a malicious attacker did manage somehow to buy a majority of staked PNK:*** The community would realize that it is under attack, particularly if the attacker uses his new PNK to commit obvious miscarriages of justice. In this case, Kleros would lose credibility as an arbitration platform and the value of PNK would decrease. Then the attacker would take a substantial loss on the PNK she bought, representing a high economic cost to carry out the attack. ***If a malicious attacker made a successful 51% attack:*** The community would perform a last-ditch defense by forking the system to remove the attackers’ holdings. Then the market would sort out which version of PNK should be used going forward. This is similar to the [ultimate appeal mechanism of Augur](https://medium.com/kleros/kleros-and-augur-keeping-people-honest-on-ethereum-through-game-theory-56210457649c). ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-542a94a9cf618263f127c363a8f5d1c3d7fe6c6b%2FPNK.png?alt=media) On the left, an attacker has managed a 51% attack and starts carrying out obvious miscarriages of justice. The community decides to fork the token removing the attackers’ holdings, and most of the users migrate to the new version of PNK.\ \ More details [here](https://kleros.gitbook.io/docs/pnk-token). ### How can I follow the dispute resolution process and be sure it has not been tampered with? Kleros protocol is committed to full transparency. Its cases are completely open and can be monitored by any person with access to an internet connection. The entire history of cases is also available and published on-chain for reference. Kleros dispute resolution procedure is documented in many places. All cryptoeconomic research is public and the code is open source. A fully working version of Kleros could be replicated in a matter of minutes by anyone with technical skills in blockchain. ### Can Kleros go beyond simple binary cases? Kleros can go beyond simple Yes/No arbitration cases to cover also multiple choices and even numerical/scalar outcomes (e.g. what is the number of electoral college votes won by Biden in the 2020 election?). We normally prescribe offering binary choices to the jury as it avoids the negative effects of vote-splitting, and allows for a small number of jurors (potentially as low as just one) to already arrive at a useful result. For complex multi-factorial cases, the [Pendulum arbitration](https://en.wikipedia.org/wiki/Pendulum_arbitration) method can be used to ask the Kleros jury to choose between two (or more sets of outcomes). ## Jurors ### Can appeals be managed outside of Kleros? Yes, it’s possible to create an arbitrable smart contract that uses Kleros for solving first instance disputes and allows appeals to be handled outside of Kleros. ### Can I use a smart contract account to stake in the court? Jurors should not stake using a smart contract account specifically in **courts where hiddenVotes are enabled** - this is because the frontend is currently unable to verify the signature. At the moment, the courts which have hiddenVotes enabled are the **General Court on Gnosis Chain** and the **Spanish General Court on both Ethereum Mainnet and Gnosis Chain.** Additionally when using a smart contract wallet, the `receive()` function may cause transfers made with `.send()` to fail. For example, receiving ETH juror rewards might fail. This is a known issue caused by the Berlin hardfork, as documented [here](https://help.safe.global/en/articles/40813-why-can-t-i-transfer-eth-from-a-contract-into-a-safe) by Safe. The Kleros contracts deployed from 2025 rely on a SafeSend mechanism which is not affected by this limitation. ### I have been drawn to rule on a dispute, can I recuse myself from the case without penalty? Jurors drawn for a dispute must participate and cannot recuse themselves. However, they can opt for a “Refuse to Arbitrate” vote under specific conditions, more details on this [below](#when-should-i-vote-refuse-to-arbitrate). Allowing jurors to recuse themselves would disrupt the balance of dispute resolution costs, which are intended to be competitive and fair, particularly in complex cases. These complex disputes demand the most from jurors, and abstention could compromise the integrity of outcomes, potentially lowering the bar for influencing decisions and thereby worsening the quality of rulings in challenging cases. ### **When should I vote "Refuse to Arbitrate" ?** There are situations where a juror should vote “Refuse to Arbitrate”: * If the General Court guidelines indicate so. For instance, the General Court guidelines may mandate refusal to arbitrate when both parties in the dispute have engaged in immoral activities, such as in an assassination market dispute. * If the specific court or sub-court’s guidelines indicate so. For example, if your case falls under the French-English translation court, its guidelines may indicate that if the disputed content is significant in size and the disputing parties fail to specify the disputed parts, jurors should refuse to arbitrate. * If the policy applicable to the case indicate so. You can easily access the court’s guidelines and the applicable policies on the case details page. As a juror, it is essential to review all the relevant documents to vote accurately. ### If parties can also be jurors, doesn't this pose a conflict of interest? / How can you ensure the jurors are perfectly impartial? The procedure for random selection of jurors among those who staked tokens in a subcourt makes it extremely hard to be selected on purpose as a juror for a case you are involved in. It is extremely hard for a juror to be able to be drawn into a court where he has a vested interest. In practice, it would be extremely unlikely for jurors having a vested interest in a case to compose a significant part of the drawn jurors and, even if that were to happen one, the appeal system would allow correcting the ruling; It is possible that internal biases still exist in jurors. There are some ways within Kleros to present information in such a way that it minimizes this bias. However, it could be also argued that no system can be completely free of biases. For an in depth discussion about this, read [this article](https://medium.com/kleros/kleros-and-mob-justice-can-the-wisdom-of-the-crowd-go-wrong-ef311209ea36). ### Do you have sample contracts that show what type of disputes could be adjudicated by Kleros? While at this point there are some sample smart contracts, this is an area that requires further development. Kleros focuses on the dispute resolution process, not on the contract drafting itself. Other companies in the ecosystem will focus on drafting contracts. In order to be arbitrable by Kleros, a smart contract needs to follow the smart contract standard we have developed. Check out our GitHub repository for more information and join our discussion on Telegram if you're interested in following the development. ### Have you considered how jurors might be vetted, as well as their experience and expertise, to enable them to participate in specific courts/disputes? In decentralized systems, the main problem of vetting jurors is: \`Who vets the vetters?\`, which is a chicken and the egg problem. One of the most attractive features of public blockchains is that anyone can join, so nobody gets to monopolize the ledger. ### How can Kleros know jurors have specific expertise if they are pseudonymous? Kleros jurors self-select into the subcourt where they wish to conduct arbitration. Kleros does not ask for the jurors' real identity or to prove they are qualified to arbitrate disputes in the subcourt where they want to work. The expertise requirement is conducted via economic incentives. Kleros generates for users the incentive to self-select for the subcourts where they have expertise. Users who self-select into the courts for which they have the right skills will, on average, make money over time. Users who self-select into courts where they don't have the right skills will lose money and tend to abandon the system. Even though, in theory, jurors may not have subject matter expertise (anyone can participate in the subcourt), in practice, users without adequate expertise would suffer an economic loss and exit the subcourt (unless they wish to lose money while they work, in order to gain those skills). This works similarly to Wikipedia in the sense that a user who does not have expertise in a field to which an article edited by him relates, may still edit the article but will likely be sanctioned by Wikipedia. ### How is the evidence presented and managed by the system? The way in which evidence is presented depends on the type of dispute. A freelancing dispute will require different evidence than an insurance or a payment dispute. Kleros Cooperative provides a back end for jurors to arbitrate disputes. The way in which it is built makes it possible for anyone to develop their own front end. The logic is similar to the Ethereum Wallet. The Ethereum Core Team provides a wallet to users, but anyone can build an Ethereum wallet. This means, for example, that an e-commerce platform could build a front end on which users could arbitrate disputes without leaving the platform. The front end would tap into Kleros' juror network. We expect many companies from the ecosystem to build interfaces based on our platform. To learn more, read this article about the evolution of Kleros Cooperative's ecosystem. ### Since jurors are drawn from a global pool, how would you make sure that they all speak the language the dispute is called in? Kleros is made of subcourts specializing in different types of disputes. Language is one of the specialization parameters. For example, there could be a “website dispute court in English”, a “website dispute court in Spanish”, “website dispute court in French”, etc. ### How do you know that jurors reviewed the evidence instead of just voting randomly? Kleros does not have a specific way to make sure that jurors reviewed the evidence. The way to make sure that jurors act honestly is through the creation of the right economic incentives. Jurors who vote randomly without reviewing the evidence are more likely to vote incoherently with the majority and lose the token they staked to be drawn. Hence, they lose money on average. Over time, this would make dishonest jurors leave the court. To learn more about how incentives work in Kleros, read the white paper. ### Are jurors required to provide a justification for their vote? Is the justification revealed to the disputing parties and to other jurors? Yes, jurors are required to provide a justification in the form of a short text. Justification is then revealed to the disputing parties as well as to other jurors after the voting is complete. ### Are there time limits for disputes? Do jurors have to respond within a given period of time? Yes, each subcourt has a time period within which jurors need to submit their decision. Jurors will be notified of pending cases in need of resolution. ### What happens to jurors who don't respond or review the evidence within the set time frame? Jurors who don't give their ruling before the deadline are penalized by losing some of their staked tokens and by not receiving the arbitration fee. ### Are jurors incentivised to rule in a way which brings them more cases in the future? Voting incoherently within the span of a single case in order to incite appeals will only cause the initial jurors a risk of losing even more money.\ As PNK and Kleros is economically and governmentally independent from all other DAOs, it is not possible for the jurors to cause more rulings to come into the Kleros Court.\ That being said, if proper juror activity on Kleros Court leads to more DAOs/partners to entrust disputes to it, then it should be seen as a good thing. ## Legal ### In legal systems such as the United States, judges are responsible for instructing jurors and explaining legal nuances. How does Kleros address questions of interpretation of legal terms in the contract? A moderator in an online forum follows some predefined rules to decide whether a user comment violated the terms and conditions. When making decisions, jurors follow similar previously defined rules, which instruct them on how to deal with legal nuances. In early stages of the project, however, Kleros was intended to be used for simpler cases, where legal nuances are not as important. ### Which are the main legal and regulatory hurdles in setting up Kleros? Because of its innovative practice based on cryptoeconomics, Kleros is not recognized as arbitration according to international agreements. This could be an obstacle for adoption in “mainstream” use cases (e.g., a government regulator could not use Kleros for settling disputes between, say, a credit card company and its users). However, this should not be an obstacle to adoption in other use cases (especially those within the crypto industry). As Kleros is able to prove that it can solve disputes in non-mainstream use cases, we expect interest to arise in mainstream use cases. Eventually, arbitration associations will accept the Kleros approach to dispute resolution. The Kleros platform is an 'opt-in' system meaning the enforcement is automatic and pre-accepted by contracting parties agreeing on using Kleros as an arbitrator. # Governance The Kleros Protocol is fully decentralized and autonomous. Here is how to participate in its governance. Anyone can propose changes to core contracts powering the Kleros ecosystem and all these changes need to be voted on and executed via community vote using PNK. ## Kleros Protocol Governance Process The Kleros Protocol Governance process consists of the decision-making and enforcement process for the different changes in parameters, contract deployments, policy specifications, incentives, and improvements that make up the Kleros protocol. Future decisions governing the protocol will be enacted through this procedure. The PNK token empowers holders with the capability to vote on proposals and collectively act as governors of the protocol. ### Steps of a successful Kleros Improvement Proposal: 1. Create a KIP (Kleros Improvement Proposal) post in the "Votes" section of the [Kleros Forum](https://forum.kleros.io/). 2. Receive community feedback and update the KIP until it can be considered non-contentious. 3. Publish a new proposal on [Kleros Snapshot](https://snapshot.org/#/kleros.eth) page to have the PNK token holders vote on it. 4. If the proposal is accepted, submit a list of transactions implementing the proposal(s) changes on [Kleros Governor](https://kleros.gitbook.io/docs/products/governor). 5. If no one successfully challenges this list, [Kleros Governor](https://kleros.gitbook.io/docs/products/governor) enacts the changes by sending the transactions. # PNK Token Kleros PNK token enables the creation of the right incentives and the prevention of Sybil attacks ⛓️ [**PNK Token Contract Address on Ethereum Mainnet**](https://etherscan.io/token/0x93ed3fbe21207ec2e8f2d3c3de6e058cb73bc04d) {% hint style="info" %} **Where to buy PNK?** * DEX Aggregators (Large Trade): 🔼 [Paraswap ](https://paraswap.io/#/)/ 🦓 [1inch](https://1inch.exchange/#/) * DEX L1 (Medium Trade): 🦄 [Un](https://app.uniswap.org/#/swap?inputCurrency=ETH\&outputCurrency=0x93ed3fbe21207ec2e8f2d3c3de6e058cb73bc04d)[iswap](https://app.uniswap.org/#/swap?inputCurrency=ETH\&outputCurrency=0x93ed3fbe21207ec2e8f2d3c3de6e058cb73bc04d) / 🍣 [S](https://app.sushi.com/swap)[ushiswap](https://app.sushi.com/swap?inputCurrency=ETH\&outputCurrency=0x93ed3fbe21207ec2e8f2d3c3de6e058cb73bc04d) / ⚖️ [Balancer](https://balancer.exchange/#/swap) * DEX L2 (Small Trade): 🔷 [Deversifi](https://app.deversifi.com) * Centralized Exchanges (Fiat Trade): 🍃 [Bitfinex](https://www.bitfinex.com/t/PNKETH) / 🚪 [Gate.io](https://www.gate.io/trade/PNK_USDT/?ch=en_sm_0421) / 🆗 [OKEX](https://www.okex.com/markets/spot-info/pnk-usdt) * Credit Card Onramp: 🛡️ [Guardarian](https://guardarian.com) {% endhint %} ## What is PNK? PNK is used both to stake (for the possibility to become a juror and to protect against attacks) and in the governance (voting rights) when new proposals, courts, or other parameters are suggested throughout our Dapps. * **Voting Rights:** PNK is used for all governance decisions taken on the Kleros platform. Users can vote with their PNK in any related votes. We already use this mechanism in our token curated list and court governance decisions. * **Staking Rewards:** Users must stake PNK in order to be able to become jurors in disputes. The more PNK a user stakes, the more chance he has of being chosen as a juror in the selected court. ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-d9a81be6b6620d09ba8e5aac7b85b1ce0a4f6618%2FPNK%20token.png?alt=media) {% hint style="info" %} **FAUCETS FOR TESTNET PNK** Call `request` function to receive 10,000 PNK. It only gives once for each address. * [Goerli PNK Faucet](https://goerli.etherscan.io/address/0x4B89e798B10478A839Ea0Abcf86C4B94A3C782A4/README.md#writeContract) (work on going to support it across all apps) * [Kovan PNK Faucet](https://kovan.etherscan.io/address/0x4e95b2e0ecb3bd394e1dddd775504820a746d3bd#writeContract) * [Ropsten PNK Faucet](https://ropsten.etherscan.io/address/0x9AdCEAa6CFd7182b838Beb085e97729EB1Da681E#writeContract) (not actively supported anymore) * [Rinkeby PNK Faucet](https://rinkeby.etherscan.io/address/0xb01c9de0e9de0a6cab6df586484707b7078de684#writeContract) (not actively supported anymore) * *Contact the Kleros team if you need a PNK faucet on other testnets* {% endhint %} ## Why Kleros Needs a Native Token? At Kleros we are building a blockchain-based, crowdsourced dispute resolution platform. An essential part of the mechanism-design is the native Kleros token (PNK). ![A Pinakion](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-e363152103c0be4206e71e002be1886c63e00307%2F1_EcUD_ah2EGIoMRVl8L8o0A.jpeg?alt=media) The PNK ticker comes from "Pinakions" originating from Ancient Athens. These small bronze plates on which citizens’ names were written were inserted into a randomizing machine that selected for participation in juries and certain civil service roles. The name of the token used by Kleros is a reference to this practice. For each dispute that is arbitrated by Kleros, some number of jurors are required. A jury as small as three people may provide an initial ruling of a dispute. Then if one of the parties decides to appeal the ruling, the number of jurors in subsequent rounds increases. PNK holders can stake their tokens in a Kleros court to indicate their availability to serve as jurors. However, eventually, we will implement specialized subcourts and PNK holders will be able to choose which subcourts to stake their token in. In order to select the jurors for a case, random PNK are drawn from among those who have been staked, and the people who hold these PNK are the jurors. {% hint style="info" %} **TOTAL SUPPLY** PNK current total supply is 764,626,704 PNK. The supply can only be modified by the Kleros community through a DAO governance vote. {% endhint %} ## Why Does Kleros Need its Own Token? First and foremost, PNK is a protection against [Sybil attacks](https://en.wikipedia.org/wiki/Sybil_attack). In order for an attacker to flood the juror pool, they need to buy enough PNK so that they are selected enough times to be a juror for the same case in order to change the outcome. Generally, this means that the attacks need 51% of the total (staked) tokens. An attacker may get lucky in rare circumstances and be selected for two of three juror spots with only a minority of the PNK. However, in order to maintain the attack through the appeal process, it would need to be selected for the majority of the juror spots on larger and larger juries, which will only be possible if the attacker actually has a majority of the PNK. Hence, substantial economic resources are required to perform a 51% attack. So far, this would still be true if we had potential jurors stake ETH instead of PNK. However, using a native token offers several key advantages for minimizing the risk of 51% attacks versus using an external cryptocurrency. ### PNK makes an attack hard If would-be jurors were drawn based on how much ETH they had staked (rather than PNK), it would be much more viable for an attacker to try to buy enough ETH to outspend the rest of the market. If an attacker wants to obtain 51% of PNK, market liquidity will dry up. As the attacker buys PNK, it will start to become scarce and each additional PNK will cost more and more. The attacker may not even be able to find 51% of PNK for sale on the open market at any given time. In contrast, consider the situation of an attacker who wants to buy enough ETH to make a stake that is greater than whatever would be already staked in Kleros courts at a given time. There is a lot of ETH floating around, and Kleros will presumably only represent a part of the broader Ethereum ecosystem. [Current 24 hour market volumes for ETH are hovering around 2–3 billion USD with all time highs near 10 billion.](https://coinmarketcap.com/currencies/ethereum/) If someone wanted to buy enough ETH to overwhelm whatever is staked in Kleros, it probably wouldn’t take them all that long. Moreover, the market for ETH is much [deeper](https://en.wikipedia.org/wiki/Market_depth) than the market for PNK will be. So, while a large purchase of ETH might move the price of ETH a bit, market liquidity effects wouldn’t come to Kleros’ defense in the same way as they do by having a native token. ### PNK makes an attack expensive Imagine that someone **does** buy 51% of the PNK in an effort to attack Kleros. Maybe their attack will be subtle and go unnoticed. However, more likely the community will realize that it is under attack, particularly if the attacker uses her new PNK to commit obvious miscarriages of justice. In this case, Kleros would lose credibility as an arbitration platform and the value of PNK would decrease. Then the attacker would take a substantial loss on the PNK she bought, representing a high economic cost to carry out the attack. On the other hand, an attack on Kleros would presumably not have that large of an impact on the price of ETH. So, if stakes were made in ETH, an attacker could perform her attack after which she could sell her ETH without taking too much of a loss. ### PNK makes Kleros forkable Finally, in the extreme case of a successful 51% attack, by having a native token, it is possible to perform a last-ditch defense of forking the system to remove the attackers’ holdings. Then the market would sort out which version of PNK should be used going forward. This would of course be highly disruptive as any pre-existing contracts designating Kleros as their arbitrator would continue to use the old version of PNK by default. Still, it would offer the community a path forward out of disaster that would not be available without a native token. This is similar to the [ultimate appeal mechanism of Augur](https://medium.com/kleros/kleros-and-augur-keeping-people-honest-on-ethereum-through-game-theory-56210457649c). ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-542a94a9cf618263f127c363a8f5d1c3d7fe6c6b%2FPNK.png?alt=media) On the left, an attacker has managed a 51% attack and starts carrying out obvious miscarriages of justice. The community decides to fork the token removing the attackers’ holdings, and most of the users migrate to the new version of PNK. Ultimately, the integrity of juries is the essence of what the Kleros protocol aims to provide. As such, it is key to maximize their defense against 51% attacks. This is why Kleros needs its own native token. **More details:** ## Conclusion To summarize, Kleros needs its own token as a defense against 51% attacks. This token gives users the ability to be selected as jurors. As such, users should have an interest in holding PNK tokens because of the opportunity that these tokens represent to receive fees and rewards for coherence for arbitrating disputes. # They talk about Kleros What people have to say about Kleros decentralized courts ## Vitalik Buterin {% embed url="" %} !["Just Use Kleros"](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-67b4fb9236d939baa2046c3f04192ec275b80b4d%2Fimage.png?alt=media) ## Naval Ravikant {% embed url="" %} ## Balaji Srinivasan {% embed url="" %} ## Chris Burniske {% embed url="" %} ## Boston University {% embed url="" %} ## #AskVitalikBA {% embed url="" %} ## University of Valencia {% embed url="" %} ## What do I think About Network States? - Vitalik Buterin **Full Article:** [**https://vitalik.ca/general/2022/07/13/networkstates.html**](https://vitalik.ca/general/2022/07/13/networkstates.html) ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2F3cF4gTgxU5jb8cnFCjAt%2F9673AC3A-3821-4055-BF2A-959F64836708_4_5005_c.jpeg?alt=media\&token=18d41caf-9999-41f2-9d92-8271267e5df0) # Court The heart of the Kleros Dispute Resolution Protocol ⚖️ [Kleros Court App](https://court.kleros.io) ⚖️ **Kleros Court** is the core engine of the Kleros portfolio of services and products.\ \ It is a dispute resolution protocol that provides arbitration for the type of subjective conflicts that smart contracts do not address. This is done by having a set of jurors randomly drawn for each dispute and having them vote to ensure a given verdict. ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-59f8cecba17df50d7045cd116d47cc866b42428f%2Fimage.png?alt=media) {% content-ref url="/pages/-MRL30KQRi7iuE9-VQKM" %} [Kleros Analytics](/integrations/analytics) {% endcontent-ref %} ### Understanding How Kleros Works Kleros works in a simple way. Disputes are created by dApps and sent to the [Kleros Court](http://court.kleros.io). All dApps send their disputes to the 'arbitrator side' (meaning the court), thus their side is called the 'arbitrable side'. ![Arbitrable side and Arbitrator side](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-8d377e7918f3509618161378338a8cfeacfcf2b7%2Faa1%20\(2\).jpg?alt=media) ### Kleros Court Process The Kleros court process works in the following way: * Once a Dapp sends a dispute, the system randomly picks jurors in a court specified for the case in question. * The case enters the evidence submission period where all interested parties (disputing parties, jurors, challengers, and any external agent) are able to submit their evidence. * After the evidence period is finished, jurors are able to vote on the case. For now, Kleros jurors can vote 'Yes', 'No' and 'Refuse to Arbitrate'. The third option is available in cases of an invalid submissions, illegal or morally unacceptable content or evidence. ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-955f2f1bbb20773420a1a3f476650f3738d78eca%2FKleros%20Arbitration.png?alt=media) {% content-ref url="/pages/-MQvMhYBcnNuoN1maV\_w" %} [Kleros Juror Tutorial](/products/court/kleros-juror-tutorial) {% endcontent-ref %} ### Courts and sub-courts When creating an arbitrable contract, parties should choose a type of court specialized in the topic of the contract. A software development contract will choose a software development court, an insurance contract will select an insurance court, etc. The structure of the set of courts forms an arborescence with the General Court as the root. ![Tree of Kleros Courts](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-ea1f8ea7da8b9b202dfe79ae6beb365120883739%2FKleros%20Courts%20Tree%20\(1\).jpg?alt=media) The description of the courts can be found on the [Kleros Court App](https://court.kleros.io) by clicking on "Join a court" button. {% content-ref url="/pages/-MTeEGQgLMMGeXe-k1Ls" %} [Smart contract integration with Kleros Court (Arbitrator)](/integrations/types-of-integrations/1.-dispute-resolution-integration-plan/smart-contract-integration) {% endcontent-ref %} # Kleros Juror Tutorial How to use Kleros Court as a Juror So, you'd like to become a Kleros juror! The process is quite simple. There is no personal information needed and there is no registration process - in short, all you have to do is get your PNK ready and stake in our courts! To help in the process of getting you up to speed, here is our full-fledged Kleros Juror Starter Kit. ## Becoming a Juror In order to become a juror, there is no sign up, no personal information needed. The only thing you need are the proper tools and your own skills. The basic outline of what needs doing to become a Kleros juror, in short. ![](https://blog.kleros.io/content/images/2020/09/Jurors-start.png) ### Tooling To start using the Kleros Court, you first need to get a [Metamask wallet](https://blog.wetrust.io/how-to-install-and-use-metamask-7210720ca047) and [buy some PNK](https://blog.kleros.io/how-to-buy-pnk-on-bitfinex-exchange/), with some ETH on the side to pay for gas fees. If you don’t have PNK yet, the easiest way to obtain some is to go to the Court interface and just click ‘Buy PNK’ from the top right of the courts homepage. The fastest way to obtain PNK is to get it directly from the ["Buy PNK"](https://court.kleros.io/tokens) page of the Court or using one of the exchanges listed there. ![](https://lh4.googleusercontent.com/UAFeO_EN4QapE-HVAxhyLnrnr6MEww84fTKkIJX0BzWRX7G664rC08wyXSz2Xvfe0pDqqBZ3dNBrQNHajz-mK-96BLIzHIVHpW3dLo-2_Mid1iJ4FKLLl4Q5aDO1m-GKJ_bu3V-C) Once you've obtained your PNK, all that remains is to stake it. Since the Court is decentralized, jurors have to vet themselves to see whether they're specialized in a specific court's field. ### Staking and cases You're a beginner juror? We warmly recommend the Onboarding Court. Have a basic knowledge of blockchain technologies? Maybe staking in the Blockchain Non-Technical Court could be up your alley. A master of the English language? Perhaps staking in the English Court is your game. Once you’ve taken a look at the courts, what remains is to stake your PNK and wait a bit to get drawn. The juror process looks something like this: * Go to the [Kleros Court](https://court.kleros.io/). In the header, click on "Courts" and then "Join a Court". ![](https://lh5.googleusercontent.com/iZM7CkC3W3B9_vjpHizGjSwj9EUFfw3luoUDQm6CJnepjbNmM6q8bsk9yuiQ1r5VE050QYkmd833-X7y8GRNICoE0wGp8WHv_92BK4K_yl9gvELflBA1VhlVFgD1n459iNFK0rjq) * Next, you will see the default ‘General Court’ selected. This is the parent court, so you can click down the court tree to see each court’s description and requirements. For this example, we will click through the ‘General Court’ court to the ‘Curation’ court. ![](https://blog.kleros.io/content/images/2020/07/image-19.png) * Once you pick a court, you can click on the large blue button that says ‘Stake’. **Note: Once you stake in a certain court, you are automatically staked in all courts above it up to the General Court.** This is for purposes of [appeals](https://blog.kleros.io/kleros-decentralized-token-listing-appeal-fees/), primarily. * When the ‘Stake’ button is clicked, you can set the amount of PNK you would like to put into the system. The chances to be drawn as a juror depends on the amount of PNK you stake. The minimum stake in the Onboarding Court is at this moment 1000 PNK, while the higher stake Curation Court has a minimum stake of 1600 PNK. ![](https://blog.kleros.io/content/images/2020/07/image-15.png) * Pay the gas fee in Metamask to confirm the staking transaction. * Once the fee is paid and the transaction confirmed you can return to the 'Courts' page and see your staked PNK in the court you have chosen. Below, we can see a user has staked a 3000 PNK. As a reminder - the higher the stake, the higher the chance of being drawn for cases on any court. ![](https://blog.kleros.io/content/images/2020/07/image-16.png) * In the above image, you can immediately get an overview of the reward each juror will receive by voting coherently. Additionally, **each court has an amount of PNK that will be locked into the case once you've been drawn as a juror, which is a constant PNK amount per vote you have and varies from court to court.** * If you are successfully drawn as a juror you will see something similar to the below in the 'My Cases' page. By clicking 'See Details' you can then review the case, evidence and make your vote. ![](https://blog.kleros.io/content/images/2020/07/image-17.png) * Users can be notified to any cases, challenges or changes in state of a dispute by signing up using the email icon in the menu header. ## The Kleros court process ![Kleros Court process](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2FanPuZOrP5JrAUT0KHt1k%2Fimage.png?alt=media\&token=67762a69-d1f1-46fd-8c36-6c05fa54afc7) **Important note: before you vote, review the policies carefully.** Have fun and see you in court! # Famous Kleros Cases Kleros Court cases that made history ## 1/ Case #532 - 2020 US Presidential Election Omen Market [Case #532 results](https://klerosboard.com/1/cases/532) ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-5916bedbec08c81581619ddc836f6b3fc59691f5%2Fimage.png?alt=media) In December 2020, the outcome of an Omen prediction market asking the following question "Will Joe Biden win the 2020 United States presidential election?" was challenged and ended up being ruled by Kleros arbitration. A lively debate occurred in social media around the validity of the market as one side argued that the final result could not be known at the time of market resolution. Case #532 ended with a ruling in favor of the "Yes" option, settling more than $2.5M (at the time) of payouts.\ \ Learn all about it by opening the Twitter thread below: {% embed url="" %} {% hint style="info" %} **Examples of evidence material:** * [Evidence A](https://cdn.kleros.link/ipfs/QmPxshJDife5p9m9upLJER5VumMDqfTqQneSWXXrNCSmYh) * [Evidence B](https://cdn.kleros.link/ipfs/QmfMGWZDdQpxB4hhHppg18qCt4skhZjEwPBgN16Ek5b5Tm) * [Evidence C](https://cdn.kleros.link/ipfs/QmUjb7qmcyPqvZkehdS38JJK8mzzic4BpwWhabZf67yhVt) {% endhint %} {% embed url="" %} {% embed url="" %} {% embed url="" %} ## 2/ Case #302 - Number of US COVID Deaths Omen Market [Case #302 results](https://klerosboard.com/1/cases/302) ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-67ebc0ecb5228f01ebbd9483a8eb9d41b59bebaa%2Fimage.png?alt=media) In August 2020, the outcome of an Omen prediction market asking the following question "Will there be a day with at least 1000 reported Corona death in the US in the first 14 days of July?" was challenged and ended up being ruled by Kleros arbitration. A lively debate occurred in social media around this market resolution as different sources for the number of daily Covid deaths were reporting contradictory data. Case #302 ended with a ruling in favor of the "Yes" option, settling more than $2.5M (at the time) of payouts. [The Block Research report on case #302](https://www.theblockcrypto.com/research/74440/a-dive-into-omen-kleros-and-blockchain-enabled-court-systems) Learn all about it by opening the Twitter thread below: {% embed url="" %} {% hint style="info" %} **Examples of evidence material:** * [Evidence D](http://case302.eth.link) * [Evidence E](https://cdn.kleros.link/ipfs/QmUk45qhoxF1jPuoHsQDdMnQqk5S81JVFE4aEhm6PgpZGX) {% endhint %} {% embed url="" %} {% embed url="" %} ## 3/ Case #16/#62/#89 - Listing of Baer token on Ethfinex [Case #16](https://klerosboard.com/1/cases/16)/[#62](https://klerosboard.com/1/cases/62)/[#89 Results](https://klerosboard.com/1/cases/89) ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-cba50e7152970f8f59e834b56b8b5e899ab75dfc%2Fimage.png?alt=media) Kleros Tokens registry was used at the time to curate tokens to be listed on the Ethfinex exchange in a decentralized manner. One of the famous examples of cases originating from this decentralized listing process is the listing of Baer token. This token was rejected because the community was able to prove that the project was a scam: * Their CTO was fake (member of a non-existent group at Oxford University - checked with a phone call), * Suspicious changes to the whitepaper, * Fake social media profiles, Baer Chain was then classified as a Ponzi scheme by the Chinese government a few months later. {% hint style="info" %} **Examples of evidence material:** * [​Evidence F​](https://cdn.kleros.link/ipfs/QmV7cM4hYrx2sdbH4mMUspBz5ACRJZ4wzU8Hrys7jZ7H1r/claim-against-brc-token-elligibility-2.pdf) * [​Evidence G](https://cdn.kleros.link/ipfs/QmckzrdTb2yb7o5iEJXQxnTjde2a1LAZMBZgUss9GUWeAa/claim-against-brc-token-elligibility.pdf) * [Evidence H](https://forum.kleros.io/t/kleros-t2cr-weekly-rundown-the-case-of-the-baer-chain-ethfinex-badge-submission/212) {% endhint %} {% embed url="" %} ## 4/ Case #554 - Registration of Kevin Owocki to Proof of Humanity [Case #554 Results](https://klerosboard.com/1/cases/554) ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-c1bc444b7883eb877b41138bc8126da61d731b07%2Fimage.png?alt=media) Proof of Humanity is a Sybil-resistant list of humans using social vouching and Kleros arbitration to endure no fake/duplicate/incorrect profiles make it into the regisrty. [Kevin Owocki](https://twitter.com/owocki?lang=fr), the founder of [Gitcoin](https://gitcoin.co), submitted his [profile ](https://app.proofofhumanity.id/profile/0x00de4b13153673bcae2616b67bf822500d325fc3?network=mainnet)into PoH but got challenged because the policy asked for a "front-facing picture" and he provided one where he was looking at an angle from the photograph. Long debates ensued to clarify what a front-facing picture meant and what would an acceptable angle be. The profile was finally rejected but Kevin Owocki was of course able to submit another one and make it into the registry. {% hint style="info" %} **Examples of evidence material:‌** * [​Evidence I](https://cdn.kleros.link/ipfs/QmUUgeMLZPM3d5b2tnwDG5Z7waDjmveWZVr8AVgo838Quf/evidence.jpg) * [Evidence J](https://cdn.kleros.link/ipfs/QmPS8yDaeDhEh2EpPJ6r3huYto3DwFEkecUvH17GhSb3UK/Rebuttals-final.pdf) * [Evidence K](https://cdn.kleros.link/ipfs/QmNjE2ZsL3NdbqyW6Cpgg9hvvhTNdfXeMadUgx1BQ3JvNE/EvidenceSubmissionAppeal2-Final.pdf) {% endhint %} ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-c8b4881e31696f37d91df5be01ced7ff26ad36a4%2Fimage%20\(56\)%20\(2\)%20\(2\)%20\(2\)%20\(2\)%20\(2\)%20\(2\).png?alt=media) **1 hour-long street poll video asking about face angles** {% embed url="" %} ## 5/ Case #82 - Listing of Grid+ token on Ethfinex [Case #82 Results](https://klerosboard.com/1/cases/82) ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-3f1746a3bf8301af7b7779ee25089558338f2ac1%2Fimage.png?alt=media) Kleros Tokens registry was used at the time to curate tokens to be listed on the Ethfinex exchange in a decentralized manner. One of the famous examples of cases originating from this decentralized listing process is the listing of the Grid+ token. This token was rejected because the community estimated that, even if the project was legitimate, the rules required that the contracts should have been audited by a third party (and Conensys Diligence was not considered a 3rd party as Grid+ was a Consensys-incubated startup). {% hint style="info" %} **Examples of evidence material:** * [​Evidence L](https://cdn.kleros.link/ipfs/QmbvuyXczHVsQxAkEbx3Ec84uTF3ooHQixMAXAScLw3iWj/heliast-gridplus-challenge.pdf) * [Evidence M](https://cdn.kleros.link/ipfs/QmUke7s1V7pkgSCUV2nBcuwxW2jwt4LHroD2yRcNvxwyn3/gridplus-violating-4.1.pdf) * [Evidence N](https://cdn.kleros.link/ipfs/Qmb8g71Guw7Dj5kwRDKd6cXLaSVdFRWgg42mCagMmYHjGX/kleros-tcr-gridplus-ethfinex-compliance-badge-challenge-response.pdf) {% endhint %} {% embed url="" %} ## 6/ Case #92 - "Is this a Doge or a cat in the snow?" [Case #92 results](https://klerosboard.com/1/cases/92) ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-1eec568f06140f5f17d8c5e10990a669c874d935%2Fimage.png?alt=media) On July 31st 2018, the Kleros protocol was launched on the Ethereum mainnet with a pilot called "Doges on Trial". It was a curated list application that relied on user submissions to create a list of Doge memes. This cryptoeconomic experiment offered a reward of 50 ETH to whoever was able to sneak a cat image into the list. Towards the end of the experiment, the following image was submitted into the Doges on Trial website. As the image did not get challenged during the initial Challenge Period (24 hours), it was accepted into the list a day after. ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-dbe7de26d0b8c78bde3bfb592ca3ed4bc1fc2b37%2Fimage%20\(21\)%20\(1\)%20\(1\)%20\(2\).png?alt=media) {% hint style="info" %} **Examples of evidence material:** * [​Evidence O](https://cdn.kleros.link/ipfs/QmXNYjTuc9XJ325qMuUjv9YQzjEvXDnU7oevR7ZbkkEMg4/Ricky's%20Case%20for%20Doges%20on%20Trial.pdf) * [Evidence P](https://cdn.kleros.link/ipfs/Qmf77Cmd5BVzDtosxRfCmHX46qDBNp27tAKYBNkrdFPmxX/Cat%20In%20The%20Snow%20Evidence.pdf) {% endhint %} The submitter claimed that this was the image of a cat and requested the 50 ETH reward. It was the opinion of Coopérative Kleros that the submitted image did not comply with the payout policy in the sense that it did not “clearly display” a cat as stated in the rules. Coopérative Kleros and the submitter agreed to settle the dispute using the recently launched Kleros Escrow Dapp and the payment was rejected in the end. Learn more about this case: # What happens during a dispute? Basic stages of a dispute A dispute goes through several stages after a dispute is created: 1. **Evidence** - Evidence can be submitted. This is also when drawing has to take place. 2. **Commit** - Jurors commit a hashed vote. This is skipped for courts without hidden votes. 3. **Vote -** Jurors reveal/cast their vote depending on whether the court has hidden votes or not. 4. **Appeal** - The dispute can be appealed. 5. **Execution** - Tokens are redistributed and the ruling is executed. The period of each stage is different for each (sub)court. # Kleros & Credible Neutrality How Kleros implements Credibly Neutrality in the context of decentralized dispute resolution. 'Credible Neutrality' is a concept introduced by Vitalik Buterin in an [inaugural blog post on Nakamoto in 2020](https://nakamoto.com/credible-neutrality/), where it was said that "a mechanism is credibly neutral if just by looking at the mechanism’s design, it is easy to see that the mechanism does not discriminate for or against any specific people". 4 primary rules were mentioned as fundamental to any credibly neutral mechanism: 1. Don’t write specific people or specific outcomes into the mechanism 2. Open source and publicly verifiable execution 3. Keep it simple 4. Don’t change it too often Kleros has implemented these principles in the design of its Court, and added additional provisions to enhance its credible neutrality in the area of decentralized dispute resolution. #### **Rule 1: Don’t write specific people or specific outcomes into the mechanism** * Kleros utilizes **sortition** (selection by the random drawing of lots) in the juror selection process, making it very difficult for disputants and voters to collude. * As an independent arbitration service, Kleros has no direct interest in the outcome of a dispute. This is especially relevant in high-value [insurance](/integrations/types-of-integrations/1.-dispute-resolution-integration-plan/use-cases/defi-insurance) or DAO governance disputes. **Rule 2: Open source and publicly verifiable execution** * The Kleros Court's code base is entirely open source and verifiable, and all evidences and voting activity within the Kleros Courts are publicly accessible. * All the processes in Kleros Court (e.g. dispute initiation, evidence submission, ruling challenge, participation in the jury) are trustless and permissionless, allowing anyone to participate, engage and influence the course of a dispute. #### **Rule 3: Keep it simple** * The **purpose-specificity** of Kleros (i.e. the focus on dispute resolution) prevents community voting fatigue within DAOs and prevents the crypto-economic design of the DAO's governance setup to interfere with the dispute resolution process. #### Rule 4: Don't change it too often * The settings determining the rules and crypto-economics of Kleros Court are adjustable only by governance votes. * The policy for each dispute are immutable after a dispute has been initiated, preventing the rules of a dispute to change during the course of a dispute. #### Additional safeguards * Kleros Court has an appeal system that allows anyone who disagrees with a ruling to challenge it. This prevents random voting, 51% attacks and [P + epsilon](https://blog.ethereum.org/2015/01/28/p-epsilon-attack/) attacks from involving a larger pool of jurors and allowing more evidence and arguments to be presented. # Court V2 🚧 This page is under construction 🚧

Preview

# Proof of Humanity A Sybil-resistant registry of humans. ✨ [Proof of Humanity App](https://v2.poh.id/) ✨ **Proof of Humanity (PoH**) is a Sybil-resistant registry of humans, combining social verification with video submission to create a trusted list of real humans. This innovative system serves as a gateway to numerous applications requiring verified human identities, ensuring users are genuine and not fake or duplicate accounts. PoH can be seamlessly integrated into a variety of existing and emerging identity systems, enhancing their security and reliability. When applying to the list, users need to provide their name, a photo, and a short video, allowing others to verify that they are indeed human. {% embed url="" %} ## Introducing Proof of Humanity *v2* In 2021, we launched the first version of Proof of Humanity, which successfully registered almost 19,000 users. However, the Ethereum mainnet's high costs and various community challenges, which led to a fork, highlighted the need for improvements, paving the way for Proof of Humanity 2.0. Proof of Humanity 2.0 has been deployed on Gnosis Chain to reduce the fees associated with registering, making it more accessible for everyone. Proof of Humanity 2.0 introduces two exciting new features: **soulbound IDs** and **multi-chain expansion**. **Soulbound IDs** are unique, non-transferable identifiers that link each human to a single ID (PoH ID), ensuring the authenticity and permanence of their digital identity. This feature allows users to recover their reputation and assets even if they lose access to their original wallet, enhancing security and reliability. **Multi-chain expansion** allows the system to operate across multiple blockchain networks, including Gnosis Chain, enhancing accessibility and interoperability. This feature enables users to maintain and transfer their verified identity across different chains, ensuring a seamless and versatile digital experience. ## Proof of Humanity Use Cases Let’s explore some exciting use cases that benefit from Proof of Humanity. #### Online Voting & Governance PoH can be used to verify that voters are real people, thus preventing Sybil attacks where a single entity could create multiple fake identities to influence voting outcomes. #### Universal Basic Income (UBI) Distribution PoH can be used to ensure that only verified humans receive UBI payments. This prevents fraud and ensures that the benefits reach those who are genuinely eligible. #### Decentralized Social Media Platforms PoH can help ensure that users on social media platforms are real individuals, which can reduce spam, trolling, and the influence of bots. This creates a more authentic and trustworthy online community. #### Peer-to-Peer Marketplaces In peer-to-peer (P2P) marketplaces, such as those for freelance work, rentals, or second-hand goods, PoH can be used to verify the identity of participants. This increases trust between users, reducing the risk of fraud and enhancing the overall reliability of the platform. #### Universal Identifiers and Self-Sovereign Identities PoH accounts can serve as universal login methods, automatically recognized by dapps without requiring registration. #### Better Funding Mechanisms By applying PoH to Quadratic Voting, we can develop new funding models for community projects. This ensures optimal distribution of funds, as PoH's Sybil-resistance prevents manipulation by multiple fake accounts, supporting the fair allocation of resources in decentralized ecosystems. #### Anti-Spam Tool Systems often use captchas before allowing a user action in order to prevent spam. These are wasting user time and do not prevent spam from a determined user who would be willing to spend the time to solve them (or outsource the solution). People in the PoH registry could be allowed a number of captcha-free interactions (potentially high enough such that they never have to fill a captcha). #### Sidechains Secured by Proof-of-Humanity Consensus The PoH registry could also be used to create a novel type of sidechain secured by Proof of Identity with a “1 person = 1 vote” principle. This would assume an honest majority of humans in the registry and would work in a way similar to Proof of Authority sidechains. ***And many others such as social recovery, inheritance planning...*** ## The Next Level: Adding Privacy to Proof of Humanity All of these use cases can be improved upon by building new privacy layers on top of Proof of humanity that will enrich it with new capabilities. A key step for the future would be the creation of anonymous Sybil-resistant identities. Identities stored in the PoH registry currently are not anonymous. It is however possible to create private Sybil-resistant identities from them. It can be done through the use of [Traceable Ring Signature](https://eprint.iacr.org/2006/389.pdf) or other using zero-knowledge proof mechanisms. This would allow individuals to prove that they are humans and not bots while not revealing their identity. For example, certifications could be used in the context of privacy-preserving KYC by giving zero-knowledge proof showing that you are a citizen of a specific country or above a specific age without revealing who you are. Another good use of anonymous identities is being able to prove one’s reputation or scoring without detailing the full history of actions made by one’s account in the past. ### Just Start Building! Proof of Humanity is an open-source project. You are free to start integrating it into your project or building on top of it as soon as you are ready to do it. **If you need some support, feel free to reach out to Cooperative Kleros at** [**contact@kleros.io**](mailto:contact@kleros.io)**,** [**Discord**](https://discord.gg/WfmtDdGe9p)**,** [**Telegram**](https://t.me/kleros)**.** # Proof of Humanity 2.0 Tutorial: (Register & Vouch) How to register your profile, vouch for others and monitor your profile registration progress. ## [Proof of Humanity App](https://v2.poh.id/) To ensure a smooth and correct registration, make sure to follow the steps and read the Proof of Humanity Registration Policy carefully. Note that incorrect submissions will result in a profile challenge. 📌 {% tabs %} {% tab title="1/ Register your profile" %} ### ### 1/ Register your profile #### 1.a/ Go to the [PoH v2](https://v2.poh.id/) dApp. You will see the homepage of the app with the recent profiles registered in PoH. #### 1.b/ '*Connect'* your Web3 wallet Once you’re on the registry page, click ‘Connect*’* in the upper right corner. Once you click ‘Connect’, this pop-up will appear. Select the wallet you want to connect.
Once you have successfully connected your wallet, you’ll see the ‘Register’ button on the menu. Click 'Register' to formally begin the registration process. But before you proceed with the registration, make sure to read the Proof of Humanity Registry Policy. You can find the ‘Policy’ button on the menu bar.
Once you're done reading the policy, you are now ready to register. Click 'Register,' and you will be redirected to a new page where you need to fill out and confirm information to create your profile. *Take a look at the flowchart outlining the registration process:*
**1.c/ Click on '****Register****' in the upper right corner.** You can only see the 'Register' button if you have connected your wallet to the dApp. If you don't see the 'Register' in the top menu bar, it means you are either not connected (check section 1.b again) or that you have already created a profile (you should see 'PoH ID' instead).
{% hint style="danger" %} **PRIVACY WARNING:** The wallet address you are using to submit your profile will be publicly linked to your identity. If you don't want your wallet holdings and transaction history to be linked to your identity, we recommend using a new address that you seeded with funds from an exchange. {% endhint %} ### I. INFORMATION
{% hint style="warning" %} ### Before You Register on Proof of Humanity Please confirm the following before continuing: **Wallet & Identity** * The wallet will be permanently linked to your real-world identity. * Do not use a wallet that holds private or sensitive assets. \ **One Human = One Profile** * You can only have one active PoH profile. * Duplicate or simultaneous submissions can be challenged, and your deposit may be lost. \ **If You Were Registered on PoH v1** You must either: * Claim your previous Humanity ID, or * Register using the correct flow on v2 (with your old or a new wallet). Do not submit multiple registrations at the same time.\ \ **Choose the Correct Action** * Renew → If you’re extending or updating an existing v2 profile. * Claim Humanity → If your v1 profile is expired, revoked, challenged, or you changed/lost your wallet. * Revoke → If you want to remove a profile before reapplying. \ **🔍 Tip:** If unsure, search for your past profile first before submitting. {% endhint %} * **Step 1. Check Your Wallet Address:** Ensure it's the correct address you wish to associate with your PoH profile. * **Step 2. Enter Your Display Name:** This can be an official name or the name by which you're commonly known. * **Step 3. Consent Checkbox:** Carefully read and understand the statement about wallet association with your real identity. Check the box to agree. Don't forget to read the 'Details' tab. * **Step 4. Once done, proceed to Next:** Click the '*Next*' button to move forward. ### II. PHOTO
* **Step 1. Photo Guidelines:** Read the recommendations for the Photo Checklist. * **Step 2. ‘*****Take a Photo with Camera*****’:** Use the app to capture your photo. You can crop it if needed. * **Step 3. Finalize Your Photo:** Click '*Ready*' once you're satisfied with the image or click '*Retake*' if you wish to change the photo. * **Step 4. Continue:** Click '*Next*' to go to the next step. {% hint style="success" %} **TIP:** Browse through ‘*Resolved Claim*’ profiles (that means they have been accepted into the registry) to have examples of what correct profiles look like. {% endhint %} ### III. VIDEO
* **Step 1. ‘*****Record a video with camera*****’:** Record your video using the app. {% hint style="info" %} :pushpin: Your video must show you holding a sign with your wallet address (e.g., 0xFdc78b748d6Bc5f77892f6654ca73426a0D3b127) and saying the phrase:\ \ *"**I certify that I am a real human and that I am not already registered in this registry**".* {% endhint %}
The sign can show the wallet address written or printed on paper, or have the wallet address displayed on a device screen. Make sure it is the same wallet address that you use for registration and that it is complete and readable. * **Step 2. Review Your Video:** Make sure it meets the required criteria in the Video Checklist. * **Step 3. Next Step:** Click '*Next*' to proceed if you're satisfied with your video. ### IV. FINALIZE YOUR REGISTRATION * **Step 1. Double-Check Your Information:** Review all the details you've provided and revisit the [policy](https://v2.proofofhumanity.id/attachment?url=https%3A%2F%2Fcdn.kleros.link%2Fipfs%2FQmbd9QuiJ6B74faz9qqfpatU3aB5VCtmEkTf1BSZ3vk588) if necessary. * **Step 2. Submission Deposit:** Enter the required deposit amount. Remember, this deposit is refunded after successful registration or lost in case of failure. Any amount you don't contribute now can be covered later. {% hint style="info" %} Make sure you have enough xDAI or ETH loaded in your wallet to pay for the deposit and transaction fee. If you don't have the amount for the deposit yet, you can pay the deposit later, but make sure you still have enough xDAI or ETH to cover the transaction fee. The deposit is reimbursed after successful registration, and lost after failure. Any amount not contributed now can be put up by crowdfunders later.\ \ **WHAT IS THE SUBMITTER'S DEPOSIT?** The deposit is an amount you lock with the submission of your profile. It acts as an incentive for potential challengers to prove you are a fake or bot and also covers arbitration fees if a dispute is raised. If your profile goes through unchallenged and successfully registered, you’ll get your deposit back. If you are a fake or have provided incorrect information, someone can challenge your profile, and a dedicated Kleros dispute will be opened to rule on your case. {% endhint %} {% hint style="success" %} [Need XDAI? bridge to Gnosis](https://jumper.exchange/?toChain=100\&toToken=0x0000000000000000000000000000000000000000) {% endhint %} {% hint style="warning" %} **COMPLIANCE WARNING:** The information you will submit about your profile will be checked and verified by the community to ensure you are not a bot or fake and that you complied with all the guidelines. Please read thoroughly the instructions given on the submit page and check out the full [Proof of Humanity Registration Policy](https://cdn.kleros.link/ipfs/QmcEvNrofibGt1MQSCk7G1fFboiMyfHoYyns4En4kWG5hU) to ensure the info you provide is correct. You can only update information by withdrawing your profile and resubmitting it. There is no way to edit your profile (Evidences are there to argument that the case made against your profile is wrong, not to update your profile with a new video for example). If you make a mistake in your submission (ex: Displaying a wrong address in the video), it could be interpreted as a malicious attack by the challengers verifying the entry into the registry and you could lose your deposit.\ \ Submissions are final and cannot be edited. Be sure to follow all submission rules to not lose your deposit. {% endhint %} * **Step 3. Submit Your Application:** Click the '*Sign In* button. Wait for the media to upload completely. * **Step 4. Confirm the Transaction:** Once the upload is complete, confirm the transaction to finalise your registration. Once the submission is successful, your profile will enter the '*Vouching*' phase. Make sure to find a voucher and obtain at least one vouch, with your deposit paid in full, to proceed to the next phase of registration, the '*Pending Claim*'.

Here's a simplified flowchart that provides an overview of the different registration phases.

After successfully submitting your profile, your profile will initially be in the '*Vouching*' status. To progress further, the following actions are required:
And here's a more comprehensive flowchart detailing the registration, challenging of profiles, revocation, and reapplying processes for PoH v2:
Don't forget to 🔔 [SUBSCRIBE](#id-2-subscribe-to-notif) 🔔 to Profile Update Notifications to be informed of changes to your profile's status that require action. {% endtab %} {% tab title="2/ Subscribe to Notif." %} ### 2/ Subscribe to Profile Update Notifications 👷🏻‍♂️🚧 **Notification System Under Development** 🚧👷🏻‍♂️\ \ We're currently working on the notification for PoH v2. We appreciate your patience as we develop this feature. In the meantime, we recommend manually checking the progress of your profile to stay updated.\ \ Thank you for your understanding. Stay tuned for further updates! {% endtab %} {% tab title="3/ Profile Validation Process" %} ### 3/ Watch your profile go through the validation process and finalize registration (**≈** 3-5 days) Your submitted profile will start in '*Needs Vouch***'** status and will go through a '*In Review*' phase before reaching the '*Verified Human*' status.
#### 3.a/ How to go from '*Needs Vouch*' to '*In Review*' status? You need to find one person who is in '*Resolved Claim*' status and that knows you in real-life (or that can prove that you really are the person your profile describes) and ask that person to vouch for you.
This person will need to go to your profile page and click on the 'Vouch' button and sign a message from his wallet.
{% hint style="info" %} **What is the difference between 'Vouch' and 'Vouch on chain'?** 'Vouch' allows you to vouch for someone without paying transaction fees. This type of vouch is non-revocable and cannot be removed by the voucher if they later change their mind. 'Vouch on-chain' means the voucher pays the on-chain transaction fee. This vouch can be removed as long as the profile is still in the “Needs Vouch” phase {% endhint %} Once a person has vouched for you, you will see it on your profile by checking the number of vouchers and the 'Vouched by' list. {% hint style="success" %} You cannot proceed to the '*In Review*' status unless you receive ***at least 1 vouch, pay the full deposit*** and initiated ***'Advance'.*** Make sure to complete these requirements so you can move forward in the registration process. {% endhint %}
If you have the required number of vouchers, your submission deposit is fully funded (100%), your profile is the current vouched, and you've initiated advanced option, your profile should move to **“****In Review****”** status shortly. {% hint style="info" %} **Why is my profile staying in '*****Needs Vouch*****' phase?** If you’re wondering why your status hasn’t moved to **“****In Review****”** yet despite having a deposit and vouches, it’s likely because the person who vouched for you also vouched for several others around the same time. Vouches are processed sequentially, so you’ll need to wait for the applications ahead of yours to be validated first (about **3.5 days per person**) before your vouch is processed. {% endhint %} If you're still in the '*Needs Vouch*' phase and notice a mistake or need to make changes to your profile, you can do so by withdrawing your profile. However, the 'Withdraw' option is only available during the vouching phase; once you've passed this phase, you will no longer have the option to withdraw.
#### 3.b/ How to go from '*In Review*' to '*Verified Human*' status? Once your Profile is in '*In Review*' status, it will then go through a **3.5-day challenge period**. During this time, the community reviews your profile to check whether you’re legitimate and whether all the information you provided complies with the policy. If someone believes your registration is noncompliant, they may challenge it to try to claim part of your deposit. If you are not challenged during this period, you will be given the opportunity to transition to '*Verified Human*' status right after this 3.5 days period ends. In order to finalize your registration, you will need to click on the 'Execute*'* button and confirm the transaction with your wallet. *(Note that any other address can also send this transaction for you).* Once the transaction is validated, you will be in '*Verified Human*' status and you will have the capacity to vouch for other people. Your deposit will also be refunded at this time. {% hint style="info" %} **What if I am challenged?** Then, a dispute will be created in Kleros Court. \ You can provide evidence on your profile page to defend your case and monitor the progress of the dispute. Note that evidence is used to demonstrate that the reason for challenging the profile is or is not valid, it is not a tool to fix your submission mistakes. You can also appeal when a ruling is given by jurors if you don't agree with it. If the jury rules in your favor, your profile goes back to '*In Review*' phase for 3.5 days. If the jury rules in favor of the challenger, your profile goes to 'Rejected' status. {% endhint %} {% endtab %} {% tab title="4/ Vouch for a profile" %} ### 4/ Vouch for another profile You can only vouch for another profile if you are connected to the app and your profile is in '*Verified Human*' status. {% hint style="danger" %} **WARNING**: Vouching for someone means you know the person, that you are sure that they are not fake or impersonators and that you checked that their submitted information was correct (ex: the address in the video is correct and readable).\ You could get removed from the registry if you vouched for a sybil or fake submission.\ \ You will not get removed if you vouch for a profile with simply incorrect information. {% endhint %}
If you meet these conditions, go to the profile page of the person you want to vouch for (they can share the link or you can search for their exact name in the search bar) and click on the 'Vouch' button on their profile.
{% hint style="info" %} **What is the difference between 'Vouch' and 'Vouch on chain'?** 'Vouch' allows you to vouch for someone without paying transaction fees. This type of vouch is non-revocable and cannot be removed by the voucher if they later change their mind. 'Vouch on-chain' means the voucher pays the on-chain transaction fee. This vouch can be removed as long as the profile is still in the “Needs Vouch” phase {% endhint %} {% hint style="info" %} **How many vouches can I give in parallel?** You can vouch for as many people as you would like. However, your vouch will only count for one person at a time in the order they were given. This means a vouch can only be used for one submission at a time on a “first come, first served” basis. For example, assume user A is registered. A vouches for user B. User B uses the vouch and moves to '*In Review*' phase. Then A vouches for user C. Since the vouching of A is already in use by B, C remains in the '*Needs Vouch*' phase for now, but will move to '*In Review*' phase once B is registered. {% endhint %} Note: You can remove your 'on chain vouch' at any time prior to the '*In Review*' phase by going to the vouched person's profile and clicking on 'Remove Vouch'.
{% endtab %} {% endtabs %} # Proof of Humanity Tutorial (Remove & Challenge) How to challenge a profile, remove your own or someone else's profile and resubmit. ❓ Check out the [FAQ ](https://kleros.gitbook.io/docs/products/proof-of-humanity/poh-faq)or [Part 1 of the PoH Tutorial](https://kleros.gitbook.io/docs/products/proof-of-humanity/proof-of-humanity-tutorial) if you don't find your answer here. {% tabs %} {% tab title="5/ Challenge a profile" %} #### 5/ Challenge a profile in "Pending registration" status. If you want to help to maintain the PoH registry and earn money by spotting fake, bot, and incorrect profiles, you will need to learn how to challenge these types of profiles when they are in "Pending Registration" status. **5.a/ Browse through the "Pending registration" profiles and check them** * Go to the [PoH app](https://app.proofofhumanity.id) and filter the profiles for "Pending Registration" profiles. The filter is on the right just above the profiles and below the total number of profiles. ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-8a6bd4986ed72cb1883e946552b55f41a35f5391%2Fimage.png?alt=media) * Once you have applied the filter, click on each profile one by one to check if their information, photo, and video follow the [PoH guidelines](https://cdn.kleros.link/ipfs/QmXDiiBAizCPoLqHvcfTzuMT7uvFEe1j3s4TgoWWd4k5np/proof-of-humanity-registry-policy-v1.3.pdf) or if you can spot impersonators or deepfake videos. {% hint style="info" %} You can use deepfake detection tools such as [https://deepware.ai/](https://deepware.ai), [https://sensity.ai/](https://sensity.ai) or other more powerful deepfake detection algorithms to help you in this enterprise. You can also use Voice Recognition Software to spot computer-generated voices or compare old and new submissions. {% endhint %} * If you find a malicious/incorrect profile, ensure you have enough funds is your wallet and challenge the profile by clicking on the "Challenge request" button at the bottom left. ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-74c25af0823d9aceef758ec43744e8e291ed50bb%2Fimage.png?alt=media) * This will open a modal asking you for a reason to the challenge. Select the relevant reason and click on "Challenge Request". ![](https://lh5.googleusercontent.com/i_FY-o4RLOghfhPv3GqEszL6ms8qf5ebFVjJpEwWFmzCw935nIzSuF1g5CiNvK0LPTiYq_jGFnHci_9CMwXdYRTmdlNRM1jtDJb7dm9TnfyYLdjfLBXSRNWVuGVbFocE1R7JDRLB) * Send the Transaction with the challenger deposit. Once the transaction is validated, the profile will soon go to "Challenged Registration" status. {% hint style="info" %} **What is the Challenger Deposit?** The deposit is an amount of ETH you lock with the challenge of the profile that will act as a deterrent to prevent people from challenging profiles for no valid reason. If your challenge of the profile is successful, you get your challenger deposit back and earn the submitter deposit (minus arbitration fees). If you have challenged a valid profile, you will lose this deposit. {% endhint %} * A dispute will then be raised in [Kleros Court](https://kleros.gitbook.io/docs/products/court) where jurors will vote on a ruling. Anyone can submit evidence from the profile interface (at the bottom of the page) ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-226b2c5a07618a917ace94081d45aa30b0459401%2Fimage.png?alt=media) ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-a201a658a71514f279a0c9d57aec02c7623f7ab8%2Fimage%20\(38\).png?alt=media) * Now, you just have to monitor the progress of the dispute through the profile interface over the following 5 to 7 days. If you don't agree with the final ruling, you will have the possibility to appeal. {% endtab %} {% tab title="6/ Remove a profile" %} #### 6/ Remove a profile from the registry **6.a/ Remove your own profile still in "Vouching Phase"** * In order to remove your own "Vouching Phase" profile, you need to go to your profile page and click on the "Withdraw Submission" button. ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-959094c77c688c789c04027eeb249f89e6eb54f6%2Fimage%20\(12\).png?alt=media) * You will get your deposit back once the transaction is validated. **6.b/ Remove a profile in "Registered" status** * In order to remove a registered profile, you need to go to the registered profile page and click on the "Request Removal" button. ![](https://blog.kleros.io/content/images/2021/03/image-7.png) * In your removal request, you will be asked to lock up a deposit (incentive for people to challenge your request + potential arbitration fees) that will be reimbursed to you if your request is successful. * In your removal request or after sending the request, you can submit evidence to back up your request. ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-2a5c92b42d0c3389dbd2e8c4230607d0ae57cb4d%2Fimage.png?alt=media) {% hint style="success" %} ***Example 1. Send a removal request from the same address as the submitter.*** **Evidence Name**: Self-removal of submission. **Evidence Description**: I am the submitter as proven by my address and I want to remove this submission\_**.**\_ {% endhint %} {% hint style="success" %} ***Example 2: Send a removal request to remove a malicious deepfake submission*** **Evidence Name**: Removal of deepfake submission. **Evidence Description**: I have analyzed the video of the submitter and the reproducible report attached in this evidence proves that it is a deepfake. {% endhint %} {% hint style="success" %} ***Example 3: Send a removal request from a different address than the submitter.*** **Evidence Name**: Self-removal of submission. **Evidence Description**: I am the submitter and I want to remove this submission. The video attached is a recording of myself saying the sentence “I want to remove my own submission from the Proof of Humanity registry.” {% endhint %} **6.c/ Remove a profile in "Pending Registration" status** * You will need to challenge the profile as explained in the [previous tab](https://kleros.gitbook.io/docs/products/proof-of-humanity/proof-humanity-tutorial-remove-and-challenge#5-challenge-a-profile-in-pending-registration-status). {% endtab %} {% tab title="7/ Resubmit/Reapply a profile" %} #### 7/ Resubmit a profile **7.a/ Resubmit a profile from a new address** * The first step is to ensure that your profile linked to your old address is in "Removed" status (because we want to avoid submitting duplicates of the same person in the registry which could be challenged). ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-2995fe3f2d7c69887c9e735f8448464209883e51%2Fimage%20\(49\).png?alt=media) * For this, go directly to your profile page using *`https://app.proofofhumanity.id/profile/youraddress?network=mainnet`*or click on "My Profile", and check that it is in "Removed" status. If it's not, remove it using these instructions in the [previous tab](https://kleros.gitbook.io/docs/products/proof-of-humanity/proof-humanity-tutorial-remove-and-challenge#6-remove-a-profile-from-the-registry). * Then, connect your new Ethereum address to the app, and [submit your new profile](https://kleros.gitbook.io/docs/products/proof-of-humanity/proof-of-humanity-tutorial#1-register-your-profile-5-10mn) like you did the first time. **7.b/ Resubmit a profile from the same address** * The first step is to ensure that your profile linked to your old address is in "Removed" status (because we want to avoid submitting duplicates of the same person in the registry which could be challenged). ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-2995fe3f2d7c69887c9e735f8448464209883e51%2Fimage%20\(49\).png?alt=media) * For this, go directly to your profile page using `https://app.proofofhumanity.id/profile/youraddress?network=mainnet`or click on "My Profile", and check that it is in "Removed" status. If it's not, remove it using these instructions in the [previous tab](https://kleros.gitbook.io/docs/products/proof-of-humanity/proof-humanity-tutorial-remove-and-challenge#6-remove-a-profile-from-the-registry). * Then, locate the "Resubmit Profile" button at the bottom left of your profile and click it. **7.c/ Reapply a profile expired or soon-to-be expired** * When your profile is expired (two year after registration) or soon before expiration, you will need to reapply to the registry to prove you are still alive and in control of your Ethereum address {% endtab %} {% tab title="8/ Reapply a profile" %} Reapplying is a proof that you are still alive and want to continue your registration. When your profile is near expiry, a button to “Reapply” will appear. You may or may not renew your profile registration. If you don’t reapply, your profile will expire and the UBI drip to your Ethereum address will stop * To Reapply, go to your profile page by clicking on “My Profile” then click on “Reapply” ![](https://lh3.googleusercontent.com/o_SG_QHoRYcPuHVe9WreYL_mJdj_T6C2nH4nkkJRvluKNlnD29qzoHJ8YpU7PjRtRgZx_lk3MRFxJ44Oe043RRgft7JZ0MQcD0QUGhqt24i3ffqgRGlSBO8lrpWYK2cX4QS4mX4X) * Fill out the form (like in your initial registration) where you’ll be redirected to, but this time the display name is prefilled. Be sure to follow all guidelines ![](https://lh4.googleusercontent.com/P3nBXoGVZDVrkazF7PJc8MS3xEb2v-DIEYHR4wnyDme4U5yvEvk0XjsG14UG24YOYLLN1uxFgnaGz9vJfbjtfRElGtOHoQ9qAin33mMno6gtt6A6iQtRYWHVl7UwJypOmvegrAl7) * Once the files are uploaded, it’ll trigger a signature confirmation popup for your reapplication. Click on “Sign” ![](https://lh6.googleusercontent.com/13wdVkznsLHTuuqqzjYerpkJ02_JkLfEpjhIQr99_N-8f9sHdJ9Sktug-LJP98I1yhMd84VC-GbvxvI2d3h4vo3jNv3_w7zxXV7DUXBJcl1jyQTKu-N5z269wrjiD0CxxYipVuMa) ![](https://lh5.googleusercontent.com/2P3takJLYKkE_HQp4UyvvCie2a7oAC0McKmZBVfLbD3Qpcj2XR6DTaJlDGoOJWKbnAvN_kQAcnm46xNyG2-AiCF3KmIfJJYeKh-Xlbo8XvmnXl2_LfbA1EU_wdhQtRfQpreWg3xN) * Then, another wallet pop up will appear for you to confirm the on-chain transaction (ETH Deposit + blockchain fees). Once your transaction is confirmed, your reapplication will go through the same phases as your initial registration except that you don’t need to be vouched for gas-vouched profiles. * For gasless vouch, you may need to be vouched again as gasless vouch has expiration time. {% endtab %} {% endtabs %} # Proof of Humanity 2.0 Tutorial (Remove & Challenge) How to challenge a profile, remove your own or someone else's profile and resubmit. ❓ Check out the [FAQ ](https://kleros.gitbook.io/docs/products/proof-of-humanity/poh-faq)or [Part 1 of the PoH Tutorial](https://kleros.gitbook.io/docs/products/proof-of-humanity/proof-of-humanity-tutorial) if you don't find your answers here. {% tabs %} {% tab title="5/ Challenge a claim" %} ### 5/ Challenge a claim If you want to help to maintain the PoH registry and earn money by spotting fake, sybil, deceased and incorrect profiles, you will need to learn how to challenge these types of profiles when they are in '*In Review or Removal Proposed*' status. **5.a/ Browse through the '*****In Review*****' or '*****Removal Proposed*****' profiles and check them** * Go to the [PoH app](https://v2.poh.id/) and filter the profiles for '***In Review*** or '***Removal Proposed***' profiles. The filter is on the right just above the profiles * Once you have applied the filter, click on each profile one by one to check if their information, photo, and video follow the PoH guidelines or if you can spot deepfake photo and videos. {% hint style="info" %} You can use deepfake detection tools such as [https://deepware.ai/](https://deepware.ai), [https://sensity.ai/](https://sensity.ai) or other more powerful deepfake detection algorithms to help you in this enterprise. You can also use Voice Recognition Software to spot computer-generated voices or compare old and new submissions. {% endhint %} * If you find a profile that violates the guidelines, ensure that you have enough funds in your wallet and challenge the profile by clicking on the 'Challenge' button at the top right of the profile page. ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2FZwKrliwBoUVaOoz0EYXh%2Fchallenge.png?alt=media\&token=e748bbda-e331-4139-b68c-5e426f949523) * This will open a modal asking you for a reason to the challenge. Select the relevant reason and include justification then click on 'Challenge request'. challenge prompt on Gnosis network * Send the transaction with the challenger deposit. Once the transaction is validated, the profile will soon go to 'Challenged or Removal Challenged' status.

a sample dispute from a Sepolia testnet profile

{% hint style="info" %} **What is the Challenger Deposit?** The deposit is an amount of ETH or xDAi you lock with the challenge of the profile that will act as a deterrent to prevent people from challenging profiles for no valid reason. If your challenge of the profile is successful, you get your challenger deposit back and earn the submitter deposit (minus arbitration fees). If you have challenged a valid profile, you will lose this deposit. {% endhint %} * A dispute will then be raised in [Kleros Court](https://kleros.gitbook.io/docs/products/court) where jurors will vote on a ruling. Anyone can submit evidence from the profile interface (at the bottom of the page) ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2FbHQdnN3eD9WH8i2LotcB%2Fadd%20evidence.png?alt=media\&token=6278685c-63c4-4925-a93b-a56caad59515) * Now, you just have to monitor the progress of the dispute through the profile interface over the following 5 to 7 days. If you don't agree with the final ruling, you will have the possibility to appeal.

The option is found at the top right of the challenged profile

an appeal interface from a real dispute on Gnosis

{% endtab %} {% tab title="6/ Remove a profile" %} ### 6/ Remove a profile from the registry **6.a/ Remove your own profile still in '*****Needs Vouch*****'** * In order to remove your own profile in '*Needs Vouch*' status, you need to go to your profile page and click on the 'Withdraw' button. ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Ffw2WDyipNLsQcuuhKYVI%2Fadvance.png?alt=media\&token=96cda6d5-48e4-4d59-9866-416fd41a4dd1) * You will get your deposit back once the transaction is validated. **6.b/ Remove or revoke a profile in registered status or '*****Verified Human*****'** * In order to remove or revoke a registered profile, you need to go to the registered profile page, open POH ID, and click on the 'Revoke' button. * In your revocation request, you will be asked to lock up a deposit (incentive for people to challenge your request + potential arbitration fees) that will be reimbursed to you if your request is successful. * You may submit an evidence to back up your revocation request. revocation prompt on Gnosis

revocation prompt on Ethereum mainnet

{% hint style="success" %} ***Example 1.\*\*\*\* ****Send a removal request from the same address as the submitter.*** **Evidence Name**: Self-removal of submission. **Evidence Description**: I am the submitter as proven by my address and I \ want to revoke this submission {% endhint %} {% hint style="success" %} ***Example 2:\*\*\*\* ****Send a removal request from a different address than the submitter.*** **Evidence Name**: Self-removal of submission. **Evidence Description**: I am the submitter and I want to remove this submission. The video attached is a recording of myself saying the sentence “I want to revoke my own submission from the Proof of Humanity registry.” {% endhint %} {% hint style="success" %} ***Example 3:\*\*\*\* ****Send a removal request to remove a malicious or incorrect submission*** **Evidence Name**: Removal of deepfake submission. **Evidence Description**: I have analyzed the video of the submitter and the reproducible report attached in this evidence proves that it is a deepfake. {% endhint %} **6.c/ Remove a profile in '*****In Review*****' status** * You will need to challenge the profile as explained in the previous tab. {% endtab %} {% tab title="7/ Resubmit a profile" %} ### 7/ Resubmit a profile **7.a/ ****Resubmit a profile from a new address** * The first step is to ensure that your profile linked to your old address is in '*Revoked*' status (because we want to avoid submitting duplicates of the same person in the registry which could be challenged). ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2FvKNRjXYFzpOKcr6X2tH2%2Frevoked.png?alt=media\&token=9c6cac46-3428-43de-be6b-259307735d5a) * For this, go directly to your profile page using *`https://v2.poh.id/PoHID`* or click on 'PoH ID', and check that it is in '*Revoked*' status. If it's not, remove it using these instructions in the previous tab. * Then, connect your new EVM address to the app, and [submit your new profile](https://kleros.gitbook.io/docs/products/proof-of-humanity/proof-of-humanity-tutorial#1-register-your-profile-5-10mn) like you did the first time. **7.b/ ****Resubmit a profile from the same address** * The first step is to ensure that your profile linked to your old address is in '*Revoked'* status (because we want to avoid submitting duplicates of the same person in the registry which could be challenged). ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2FvKNRjXYFzpOKcr6X2tH2%2Frevoked.png?alt=media\&token=9c6cac46-3428-43de-be6b-259307735d5a) * For this, go directly to your profile page using *`https://v2.poh.id/PoHID`*or click on 'PoH ID', and check that it is in "Revoked" status. If it's not, remove it using these instructions in the previous tab. * Then, locate the 'Resubmit Profile' button at the bottom left of your profile and click it. **7.c/ ****Reapply a profile expired or soon-to-be expired** * When your profile is expired (two year after registration) or soon before expiration, you will need to reapply to the registry to prove that you are still alive and in control of your address
{% endtab %} {% endtabs %} # Proof of Humanity 2.0 Tutorial (Transferring a Profile) How to transfer a profile to another supported chain PoH 2.0 is live on both Ethereum Mainnet and Gnosis chain. Even though you can only have your profile active on one chain at a time, you have the option to transfer from one chain to another using the same steps as below: * First, go to your profile page and click 'Transfer'

a sample from a Sepolia testnet profile

* A transfer prompt will then appear for a reminder and to confirm your transfer request.
* Once the transaction is confirmed, your profile status will change from 'Registered' to 'Pending Update'. You will then need to change your network connection to the network you want the profile to be transferred to. Once your wallet is connected to the new desired chain, go to your profile page and click 'Update state'.
* An update prompt will appear where you should initiate the 'Relay State Update' option and confirm the transaction.

a sample from a Sepolia testnet profile

{% hint style="info" %} Make sure that you have enough funds to transact on your desired new chain to update or complete the profile transfer {% endhint %} * Once the transaction is validated, your current profile request status will be in '*Resolved Claim*' with the icon of the new network it's included in, while the immediate past profile request status will change to 'Transferred'.
# Proof of Humanity 2.0 Integration Guide Integrate PoH V2 to verify real humans in your application ### Key Features * **Soulbound IDs**: Persistent human identities that survive wallet changes * **Multi-chain deployment**: Available on Ethereum mainnet and Gnosis chain * **Cross-chain transfers**: Move identities between supported chains * **Enhanced vouching**: Support for both on-chain and off-chain (EIP-712) vouching * **V1 compatibility**: Seamless migration path from V1 ### Core Concepts #### Soulbound IDs Proof of Humanity V2 introduces **soulbound IDs** that represent unique human identities. Unlike V1 where each registration corresponded to a specific wallet address, V2 uses unique humanity IDs (`pohID` or `humanityId`) that persist across wallet changes. **Key principle:** `1 human → 1 wallet address ↔ 1 humanity` If a user loses access to their wallet, they can request removal of the lost address and register with a new one using the same PoH ID, preserving their reputation and assets tied to the identity. **Recovery Process:** ```solidity // 1. Human loses access to wallet humanity.owner == lostAddress isHuman(lostAddress) == true // 2. Human requests removal of lost address humanity.owner == address(0) isHuman(lostAddress) == false // 3. Human registers with new wallet address humanity.owner == newAddress isHuman(newAddress) == true ``` #### Multi-Chain Architecture PoH V2 operates across multiple blockchains with a sophisticated state synchronization system: * **Home Chain**: The primary chain where a humanity is claimed and managed * **State Updates**: Humanity status synchronized across chains via bridge gateways * **Universal IDs**: Humanity IDs are consistent across all supported chains * **Transfer Mechanism**: Humanities can be transferred between chains with cooldown periods {% hint style="info" %} **Important**: A humanity can only have **one active home chain** at a time, but its state can be reflected on multiple chains. {% endhint %} #### Humanity Lifecycle A humanity progresses through distinct states: \ **Unclaimed** → **Vouching** → **Resolving** → **Claimed** → **Renewal** → **Expired/Revoked** ### Contract Architecture #### ProofOfHumanity Contract * Core functionality similar to V1 with enhanced soulbound features * Manages humanity claims, renewals, and revocations * Handles vouching and challenge mechanisms with dispute resolution * Supports both on-chain and off-chain (EIP-712) vouching #### ProofOfHumanityExtended Contract * Enhanced version deployed on Ethereum mainnet * Includes **Fork Module** for V1 compatibility * Allows seamless transition from V1 to V2 #### CrossChainProofOfHumanity Contract * Manages cross-chain state updates and transfers * Stores received state updates from other chains * Handles humanity transfers between chains with transfer cooldowns * Ensures consistency across multi-chain deployments #### Bridge Gateways * **AMB (Arbitrary Message Bridge)** gateways for cross-chain communication * Enable secure message passing between chain instances * Support both state updates and humanity transfers ### Deployment Addresses #### Ethereum Mainnet
ContractAddress
ProofOfHumanityExtended0xbE9834097A4E97689d9B667441acafb456D0480A
CrossChainProofofHumanity0xa478095886659168E8812154fB0DE39F103E74b2
AMB Bridge Gateway0xddafACf8B4a5087Fc89950FF7155c76145376c1e
Fork Module0x068a27Db9c3B8595D03be263d52c813cb2C99cCB
#### Gnosis Chain
ContractAddress
ProofOfHumanity0xa4AC94C4fa65Bb352eFa30e3408e64F72aC857bc
CrossChainProofOfHumanity0x16044E1063C08670f8653055A786b7CC2034d2b0
AMB Bridge Gateway0x6Ef5073d79c42531352d1bF5F584a7CBd270c6B1
### Interface Definitions Core Interface ```solidity interface IProofOfHumanity { // Core verification functions function isHuman(address _account) external view returns (bool); function isClaimed(bytes20 _humanityId) external view returns (bool); function humanityOf(address _account) external view returns (bytes20); function boundTo(bytes20 _humanityId) external view returns (address); // Detailed information function function getHumanityInfo(bytes20 _humanityId) external view returns ( bool vouching, // Is this humanity currently vouching for someone bool pendingRevocation, // Is there a pending revocation request uint48 nbPendingRequests, // Number of pending requests in challenging phase uint40 expirationTime, // When the humanity expires address owner, // Current owner address uint256 nbRequests // Total number of requests made ); // Statistics and request information function getClaimerRequestId(address _claimer) external view returns (uint256); function getNumberOfVouches(bytes20 _humanityId, uint256 _requestId) external view returns (uint256); function getHumanityCount() external view returns (uint256); } ``` #### Vouching Interface ```solidity interface IProofOfHumanityVouching { struct SignatureVouch { uint40 expirationTime; // Time when the signature expires uint8 v; // 'v' value of the signature bytes32 r; // 'r' value of the signature bytes32 s; // 's' value of the signature } // Basic vouching functions function addVouch(address _account, bytes20 _humanityId) external; function removeVouch(address _account, bytes20 _humanityId) external; function vouches(address _voucher, address _claimer, bytes20 _humanityId) external view returns (bool); // Advanced vouching with signature support function advanceState( address _claimer, address[] calldata _vouches, SignatureVouch[] calldata _signatureVouches ) external; } ``` #### Cross-Chain interface ```solidity interface ICrossChainProofOfHumanityView { // View functions (same as main interface) function isHuman(address _account) external view returns (bool); function isClaimed(bytes20 _humanityId) external view returns (bool); function boundTo(bytes20 _humanityId) external view returns (address); function humanityOf(address _account) external view returns (bytes20); // Cross-chain operations function updateHumanity(address _bridgeGateway, bytes20 _humanityId) external; function transferHumanity(address _bridgeGateway) external; // Receive functions (called by bridge) function receiveUpdate(address _owner, bytes20 _humanityId, uint40 _expirationTime, bool _isActive) external; function receiveTransfer(address _owner, bytes20 _humanityId, uint40 _expirationTime, bytes32 _transferHash) external; } ``` #### Request Management Interface ```solidity interface IProofOfHumanityRequests { enum Party { None, Requester, Challenger } enum Reason { None, IncorrectSubmission, IdentityTheft, SybilAttack, Deceased } // Request creation function claimHumanity(bytes20 _humanityId, string calldata _evidence, string calldata _name) external payable; function renewHumanity(string calldata _evidence) external payable; function revokeHumanity(bytes20 _humanityId, string calldata _evidence) external payable; // Request management function fundRequest(bytes20 _humanityId, uint256 _requestId) external payable; function withdrawRequest() external; function executeRequest(bytes20 _humanityId, uint256 _requestId) external; // Challenges and disputes function challengeRequest( bytes20 _humanityId, uint256 _requestId, Reason _reason, string calldata _evidence ) external payable; function fundAppeal(address _arbitrator, uint256 _disputeId, Party _side) external payable; // Evidence and fee management function submitEvidence(bytes20 _humanityId, uint256 _requestId, string calldata _evidence) external; function withdrawFeesAndRewards( address payable _beneficiary, bytes20 _humanityId, uint256 _requestId, uint256 _challengeId, uint256 _round ) external; } ``` ### Quick Start Integration #### 1. Install Interface ```solidity // SPDX-License-Identifier: MIT pragma solidity ^0.8.20; interface IProofOfHumanity { function isHuman(address _account) external view returns (bool); function humanityOf(address _account) external view returns (bytes20); function isClaimed(bytes20 _humanityId) external view returns (bool); function boundTo(bytes20 _humanityId) external view returns (address); } ``` #### 2. Basic Integration ```solidity contract MyDApp { IProofOfHumanity public immutable poh; constructor(address _pohAddress) { poh = IProofOfHumanity(_pohAddress); } modifier onlyHuman() { require(poh.isHuman(msg.sender), "Must be verified human"); _; } function humanOnlyFunction() external onlyHuman { // Your logic here } } ``` #### 3. Chain Selection Choose the appropriate contract address based on your deployment chain: ```solidity // For Ethereum mainnet address constant POH_ETHEREUM = 0xbE9834097A4E97689d9B667441acafb456D0480A; // For Gnosis chain address constant POH_GNOSIS = 0xa4AC94C4fa65Bb352eFa30e3408e64F72aC857bc; ``` #### Method 1: Basic Human Verification **Use case**: Simple verification that an address belongs to a verified human. **Implementation Example** ```solidity contract BasicVerification { IProofOfHumanity public immutable poh; constructor(address _pohAddress) { poh = IProofOfHumanity(_pohAddress); } function verifyHuman(address _user) external view returns (bool) { return poh.isHuman(_user); } function getHumanityInfo(address _user) external view returns ( bool isVerified, bytes20 humanityId ) { humanityId = poh.humanityOf(_user); isVerified = humanityId != bytes20(0); } } ``` #### Method 2: Soulbound Identity Integration **Use Case**: Applications requiring persistent identity across wallet changes (reputation systems, social platforms, DAOs). **Implementation** ```solidity contract SoulboundIntegration { IProofOfHumanity public immutable poh; struct UserProfile { uint256 registrationTime; uint256 reputation; string username; bool isActive; } // Store data by humanity ID, not address mapping(bytes20 => UserProfile) public profiles; mapping(bytes20 => address) public currentAddress; event ProfileCreated(bytes20 indexed humanityId, address indexed user); event AddressUpdated(bytes20 indexed humanityId, address indexed oldAddress, address indexed newAddress); function createProfile(string calldata _username) external { //First verify user is actually human require(poh.isHuman(msg.sender), "Must be verified human"); //Then get their humanity ID bytes20 humanityId = poh.humanityOf(msg.sender); require(humanityId != bytes20(0), "Failed to get humanity ID"); require(!profiles[humanityId].isActive, "Profile already exists"); profiles[humanityId] = UserProfile({ registrationTime: block.timestamp, reputation: 0, username: _username, isActive: true }); currentAddress[humanityId] = msg.sender; emit ProfileCreated(humanityId, msg.sender); } function updateReputation(address _user, uint256 _newReputation) external { //Verify user is still human before updating require(poh.isHuman(_user), "User must be verified human"); bytes20 humanityId = poh.humanityOf(_user); require(profiles[humanityId].isActive, "Profile not found"); // Update address if it changed if (currentAddress[humanityId] != _user) { emit AddressUpdated(humanityId, currentAddress[humanityId], _user); currentAddress[humanityId] = _user; } profiles[humanityId].reputation = _newReputation; } function getProfile(address _user) external view returns (UserProfile memory) { bytes20 humanityId = poh.humanityOf(_user); return profiles[humanityId]; } function getProfileByHumanityId(bytes20 _humanityId) external view returns (UserProfile memory) { return profiles[_humanityId]; } //Additional helper functions for better integration function isProfileActive(address _user) external view returns (bool) { if (!poh.isHuman(_user)) return false; bytes20 humanityId = poh.humanityOf(_user); return profiles[humanityId].isActive; } function getActiveHumanityId(address _user) external view returns (bytes20) { require(poh.isHuman(_user), "User not verified"); return poh.humanityOf(_user); } //Handle humanity expiration/revocation function deactivateExpiredProfile(bytes20 _humanityId) external { require(profiles[_humanityId].isActive, "Profile not active"); // Check if humanity is still claimed address currentOwner = poh.boundTo(_humanityId); if (currentOwner == address(0)) { profiles[_humanityId].isActive = false; } } } ``` #### Method 3: Cross-Chain Integration **Use Case**: Applications operating across multiple chains. **Multi-Chain Verification** ```solidity interface ICrossChainProofOfHumanity { function isHuman(address _account) external view returns (bool); function isClaimed(bytes20 _humanityId) external view returns (bool); function humanityOf(address _account) external view returns (bytes20); function boundTo(bytes20 _humanityId) external view returns (address); } contract CrossChainDApp { IProofOfHumanity public immutable pohMain; ICrossChainProofOfHumanity public immutable pohCrossChain; constructor(address _pohMain, address _pohCrossChain) { pohMain = IProofOfHumanity(_pohMain); pohCrossChain = ICrossChainProofOfHumanity(_pohCrossChain); } function isVerifiedHuman(address _account) public view returns (bool) { // Check both main contract and cross-chain state return pohMain.isHuman(_account) || pohCrossChain.isHuman(_account); } function getUniversalHumanityId(address _account) public view returns (bytes20) { bytes20 humanityId = pohMain.humanityOf(_account); if (humanityId == bytes20(0)) { humanityId = pohCrossChain.humanityOf(_account); } return humanityId; } function getHumanityOwner(bytes20 _humanityId) public view returns (address) { address owner = pohMain.boundTo(_humanityId); if (owner == address(0)) { owner = pohCrossChain.boundTo(_humanityId); } return owner; } } ``` ### Advanced Integration Patterns #### Event Monitoring Monitor important PoH events for real-time updates: ```solidity contract EventMonitor { IProofOfHumanity public immutable poh; mapping(bytes20 => bool) public activeHumanities; mapping(address => bytes20) public humanityToUser; event HumanityStatusChanged(bytes20 indexed humanityId, address indexed user, bool isActive); event HumanityAddressUpdated(bytes20 indexed humanityId, address indexed oldUser, address indexed newUser); constructor(address _pohAddress) { poh = IProofOfHumanity(_pohAddress); } // Call when monitoring HumanityClaimed events function handleHumanityClaimed(bytes20 humanityId, address user) external { require(poh.isClaimed(humanityId), "Humanity not claimed"); activeHumanities[humanityId] = true; humanityToUser[user] = humanityId; emit HumanityStatusChanged(humanityId, user, true); } // Call when monitoring HumanityRevoked events function handleHumanityRevoked(bytes20 humanityId, address user) external { activeHumanities[humanityId] = false; delete humanityToUser[user]; emit HumanityStatusChanged(humanityId, user, false); } } ``` #### Detailed State Queries For applications requiring comprehensive humanity information: ```solidity interface IProofOfHumanityDetailed { function getHumanityInfo(bytes20 _humanityId) external view returns ( bool vouching, // Currently vouching for someone bool pendingRevocation, // Has pending revocation request uint48 nbPendingRequests, // Number of pending requests uint40 expirationTime, // When humanity expires address owner, // Current owner address uint256 nbRequests // Total requests made ); } contract DetailedIntegration { IProofOfHumanityDetailed public immutable poh; struct HumanityStatus { bool isValid; bool canVouch; bool isPending; uint256 timeToExpiry; address currentOwner; } constructor(address _pohAddress) { poh = IProofOfHumanityDetailed(_pohAddress); } function getHumanityStatus(bytes20 _humanityId) external view returns (HumanityStatus memory) { ( bool vouching, bool pendingRevocation, uint48 nbPendingRequests, uint40 expirationTime, address owner, ) = poh.getHumanityInfo(_humanityId); bool isValid = owner != address(0) && block.timestamp < expirationTime; bool canVouch = isValid && !vouching && !pendingRevocation; bool isPending = pendingRevocation || nbPendingRequests > 0; uint256 timeToExpiry = expirationTime > block.timestamp ? expirationTime - block.timestamp : 0; return HumanityStatus({ isValid: isValid, canVouch: canVouch, isPending: isPending, timeToExpiry: timeToExpiry, currentOwner: owner }); } } ``` #### Registration Vouching Integration **Understanding PoH's Vouching System:** PoH's vouching system is **exclusively for the registration process** - when new people are trying to become verified humans. **How Registration Vouching Works:** 1. Someone calls `claimHumanity()` to register as a human 2. Existing verified humans call `addVouch()` to support them 3. Once enough vouches are collected, the request can advance to the resolving phase 4. The person either becomes verified or gets challenged ### Migration from V1 #### V1 Compatibility The `ProofOfHumanityExtended` contract includes automatic V1 compatibility through the Fork Module: * ✅ V1 registrations continue to work * ✅ No immediate migration required * ✅ Seamless transition available * ✅ `isHuman()` checks both V1 and V2 #### Migration Support Implementation ```solidity contract MigrationHelper { IProofOfHumanity public immutable pohV2; constructor(address _pohV2Address) { pohV2 = IProofOfHumanity(_pohV2Address); } function getRegistrationVersion(address _user) external view returns (string memory) { if (!pohV2.isHuman(_user)) { return "not_registered"; } bytes20 humanityId = pohV2.humanityOf(_user); // V1 users have humanity ID equal to their address if (humanityId == bytes20(_user)) { return "v1"; } return "v2"; } function shouldMigrate(address _user) external view returns (bool) { if (!pohV2.isHuman(_user)) return false; bytes20 humanityId = pohV2.humanityOf(_user); return humanityId == bytes20(_user); // V1 indicator } function isHumanAnyVersion(address _user) external view returns (bool) { // Automatically checks both V2 and V1 via Fork Module return pohV2.isHuman(_user); } } ``` #### Migration Benefits Migrating from V1 to V2 provides: * **Soulbound identity**: Persistent across wallet changes * **Cross-chain support**: Use identity on multiple chains * **Enhanced security**: Improved dispute and vouching mechanisms * **Future compatibility**: Access to new features and integrations ### Quick Reference #### Essential Functions ```solidity // Basic verification function isHuman(address _account) external view returns (bool); function humanityOf(address _account) external view returns (bytes20); // Humanity info function isClaimed(bytes20 _humanityId) external view returns (bool); function boundTo(bytes20 _humanityId) external view returns (address); // Detailed info (if needed) function getHumanityInfo(bytes20 _humanityId) external view returns ( bool vouching, bool pendingRevocation, uint48 nbPendingRequests, uint40 expirationTime, address owner, uint256 nbRequests ); ``` Contract Addresses Quick Copy ```solidity // Ethereum Mainnet address constant POH_ETHEREUM = 0xbE9834097A4E97689d9B667441acafb456D0480A; address constant CROSSCHAIN_ETHEREUM = 0xa478095886659168E8812154fB0DE39F103E74b2; // Gnosis Chain address constant POH_GNOSIS = 0xa4AC94C4fa65Bb352eFa30e3408e64F72aC857bc; address constant CROSSCHAIN_GNOSIS = 0x16044E1063C08670f8653055A786b7CC2034d2b0; ``` ### Support Resources * **Documentation**: [Proof of Humanity Docs](https://proofofhumanity.id/) * **GitHub**: [PoH V2 Repository](https://github.com/Proof-Of-Humanity/proof-of-humanity-v2-contracts) * **Support:** * **Forum**: [PoH Governance](https://gov.proofofhumanity.id/) # Proof of Humanity FAQ Frequently Asked Questions about Proof of Humanity ## What is the purpose of Proof of Humanity? Proof of Humanity (PoH) is a system designed to create a trusted list of humans, verified by a decentralized community. This system is designed to be used by individuals as a gateway to various new applications that require Sybil-resistance to function effectively. It can also be integrated into a wide range of existing and future applications that need reliable identity systems. ## Why should I register to PoH? What are its use cases? Proof of Humanity is a decentralized system that creates a trusted list of verified humans by having users submit their name, photo, and video, which are then vouched for by existing members. Registering with PoH ensures that you are recognized as a real person, preventing duplicates and bots. The benefits include secure online voting, fair UBI distribution, a more authentic social media experience, and more. PoH also enhances trust in peer-to-peer marketplaces and serves as a universal login method for decentralized applications. By registering, you help create a more secure and trustworthy digital environment for various applications. You can read more about the use cases of Proof of Humanity [here](/products/proof-of-humanity#proof-of-humanity-use-cases). ## How do I use the Proof of Humanity registry? To use the Proof of Humanity registry, we recommend following our comprehensive [tutorial](/products/proof-of-humanity/proof-of-humanity-tutorial), which guides you through the registration process step-by-step. It's important to read the tutorial first to ensure you understand the requirements and process. Additionally, please review the [Registry Policy ](https://cdn.kleros.link/ipfs/QmcEvNrofibGt1MQSCk7G1fFboiMyfHoYyns4En4kWG5hU)before applying to make sure you comply with all guidelines. ## Can I, as a single individual, have more than one identity submitted to Proof of Humanity? No, you can’t. As a single individual, you are only allowed to have one profile submitted to the Proof of Humanity registry. Multiple accounts are not permitted as they constitute a Sybil attack. A Sybil attack involves creating multiple fake identities to manipulate the system. Individuals who attempt to create multiple accounts will be identified as Sybils and will be removed from the registry. Please review the [Registry Policy](https://cdn.kleros.link/ipfs/QmcEvNrofibGt1MQSCk7G1fFboiMyfHoYyns4En4kWG5hU) before applying to make sure you comply with all guidelines. ## Which wallet address should I use to register in Proof of Humanity? The wallet address you use to submit your profile will be publicly linked to your identity. If you prefer not to link your wallet holdings and transaction history to your identity, we recommend using a new wallet address funded from a crypto exchange. ## Which phases will my profile go through before being registered?

Flowchart for Registering a New Profile

Once you submit your profile, it will enter the 'Vouching Phase' until someone vouches for you. After getting at least one vouch and paying the full submitter's deposit, your profile will move to the 'Pending Claim' phase. During this phase, anyone can challenge your profile for 3.5 days if they believe you are not a real human or if it violates the [Registry Policy](https://cdn.kleros.link/ipfs/QmcEvNrofibGt1MQSCk7G1fFboiMyfHoYyns4En4kWG5hU). If your profile isn’t challenged or if any challenges are unsuccessful, your profile will be in the 'Resolved Claim' status, meaning you are successfully registered in the Proof of Humanity registry. 📌 Incorrect submissions will result in a profile challenge. In case of a profile challenge, here's the process:

Flowchart for Challenging a Profile

If your profile is challenged, it will either go back to the 'Pending Claim' phase or be 'Withdrawn,' depending on the ruling of the Kleros Court.
📌 Once registered or in the '*Resolved Claim*', your profile can either: * expire after a year (if you don’t renew or reapply). The renewal period starts one month before the profile expires.

Flowchart for Profile Renewal

* or get revoked due to a malicious or incorrect submission, or if you want to make changes to your profile. Making changes to your profile requires you to revoke your existing profile and resubmit a new one.

Flowchart for Revoking a Profile

If your profile is 'Expired', 'Revoked' or about to expire, you can reapply for submission, bringing you back to the 'Vouching Phase'. ## Why should I vouch for someone? What's in it for me? Vouching for someone is a benevolent act in order to help people you know be accepted into the registry. Be careful with whom you vouch for. If by mistake (or excess of trust) you vouch for a malicious user, you will be penalized. ## What happens if I vouch for a malicious user? If a submission is challenged and rejected for 'Sybil attack' or 'Identity theft' reasons, all people who had vouched for the rejected profile get *removed* from the registry. This allows to weed out malicious attackers who vouch for sybils or duplicate accounts. It also means you have to be careful when vouching: make sure you know the person in real life and that it is not a duplicate. ## How many people can I vouch for? You can vouch for as many people as you like. However, your vouch will only count for one person at a time, in the order they were given. A user's vouch can only be used for one submission at a time on a “first come, first served” basis. For example, if user A is registered and vouches for user B, user B will move to the 'Pending Claim' phase. If A then vouches for user C, C will remain in the 'Vouching Phase' until B is registered or in the 'Resolved Claim', after which C will move to the 'Pending Claim' phase. ## Can I remove a vouch? You can remove your vouch at any time prior to the 'Pending Claim' phase by going to the vouched person's profile and clicking on 'Remove Vouch'. ## When does my deposit get returned? Your deposit will be returned to the funding address shortly after you move to 'Verified Human' status. ## How long does the registration last? Registrations have a duration of 1 year. This means that users need to periodically reapply to the registry. The purpose of the limited registration period is to remove people who die and malicious submissions which might have made it into the list. Conditions to reapply are similar to the original application. You can reapply before the current registration period ends (1 month before expiry) in order to avoid spending some time unregistered. Users reapplying (such that they have the required vouching and deposit) before their registration ends are considered registered for the entire period of their new application. ## What rules should I follow to submit a proper profile or to remove an incorrect one? Check the [Registry Policy](https://cdn.kleros.link/ipfs/QmcEvNrofibGt1MQSCk7G1fFboiMyfHoYyns4En4kWG5hU) to obtain all the detailed conditions for a profile to be accepted or rejected from the registry. ## Can I request to remove someone else profile from the registry? A request to remove a registered submission from the list can be made at any time by submitting a deposit and a reason for removal. ## Can I remove my profile and submit it again because I want to change something about it? How do I proceed? ### **I. If your profile is still in '*****Vouching Phase'*** If your profile is still in the 'Vouching Phase' and you want to change something, you can do so by withdrawing your current submission and resubmitting with a new and updated profile. Check our tutorial on [how to remove or withdraw a profile](/products/proof-of-humanity/proof-humanity-2.0-tutorial-remove-and-challenge). ### **II. If your profile is already registered or in the '*****Resolved Claim*****'** First, you need to remove your own existing profile and then either reapply using the same wallet address or submit with another address for a new registration. In order to remove your old registered profile, you need to go to your registered profile page and click on the 'Revoke' button and then provide evidence that you are indeed the submitter. Check out our [tutorial](/products/proof-of-humanity/proof-humanity-2.0-tutorial-remove-and-challenge). {% hint style="success" %} ***Example 1.\*\*\*\* ****Send a removal request from the same address as the submitter.*** **Evidence Name**: Self-removal of submission. **Evidence Description**: I am the submitter as proven by my address and I want to remove this submission {% endhint %} {% hint style="success" %} ***Example 2:\*\*\*\* ****Send a removal request from a different address than the submitter.*** **Evidence Name**: Self-removal of submission. **Evidence Description**: I am the submitter and I want to remove this submission. The video attached is a recording of myself saying the sentence “I want to remove my own submission from the Proof of Humanity registry.” {% endhint %} {% hint style="success" %} ***Example 3:\*\*\*\* ****Send a removal request to remove a malicious or incorrect submission.*** **Evidence Name**: Removal of deepfake submission. **Evidence Description**: I have analyzed the video of the submitter and the reproducible report attached in this evidence proves that it is a deepfake. {% endhint %} ## Why did the registry start with some users already registered in it? Since we require user vouching for new members, we had to start with an initial set of trusted and manually curated users. Those registered through the seeding event will still have to periodically renew their registration like any other user. ## Why can’t I display my ENS in my submission video? In order to reduce the attack surface at launch, we decided against allowing to display or use ENS. A user could lose control of its ENS, forget to renew it, or be outbid. ## As deepfakes get better, will challengers be able to keep up technologically to defend against this? Improvements in machine learning are likely to affect the effectiveness of both deepfake creation and deepfake detection algorithms. If algorithms manage to produce deepfakes not detectable by other algorithms, other evidence would need to be required. This can be decided through Kleros governance process. ## What if my religion forbids me from showing my face? What if I am physically unable to speak? Internal features of the face are the most important for face recognition and removing the requirement to pronounce the sentence would decrease the security of the system (speech analysis can be used to detect multiple registrations). For the moment, these edge cases do not allow the person to be registered. If you have a proposal that would enable the secure registration of this edge case (and others), you can write a about it in the PoH forum and submit it through the governance process. ## What if I have an identical twin that also wants to be registered? While most people have a hard time distinguishing twins, identical twins aren't actually identical and can be distinguished by skilled individuals. Moreover, facial recognition algorithms tend to do a better job than humans distinguishing between twins. This means a twin submission could be challenged but the twin could probably easily provide evidence that he is a twin to win the dispute. # Proof of Humanity 2.0 launch FAQ FAQs specific to the transition from Proof of Humanity 1.0 to 2.0. ## I have/had a profile on PoH 1.0 - do I need to do anything to be able to use PoH 2.0? If your profile is still valid on v1, you do not need to do anything. Your profile will be automatically readable and accessible on PoH v2 on Ethereum. You can then choose to bridge it to Gnosis chain if you need to use it on that chain. If your profile has already expired, you need to create a fresh profile on PoH v2 on either Ethereum or Gnosis chain. ## Can I have one PoH profile on each chain? No, PoH v2 profiles are singular and unique to a user across all chains. While you can create the profile on any of the supported chains (ETH, GNO), you can only have your profile active on one chain at any time. However, you can bridge your profile over to the other chain at any time if needed. ## I use my PoH profile through one through another platform (e.g. Galxe, Gitcoin Passport ...), do I need to do anything specific to make sure my profile is still recognised? No, Kleros Cooperative will be reaching out to these platforms to upgrade the integration. In case of doubt, check with the team of these platforms to see if your account with them is linked to the updated PoH v2 integration. # Curate Data Curation as a Service using TCRs (Token Curated Registries) 🗄️ [Kleros Curate app](https://curate.kleros.io) (mainnet) 🗄️\ \ **Kleros Curate** is a decentralized dApp that can be used to create open curated registries of just about anything using financial incentives and Kleros dispute resolution technology to ensure a list stays on topic and that each entry is compliant to the predefined acceptance criteria. ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-ded1a93ee57c5869058d1a6e81845d76116d29e8%2FCurate.png?alt=media) When a user submits an item to Curate, it is first vetted by a challenge period which allows anyone else to challenge that submission. If the submission isn’t challenged, it’s deemed legitimate and on topic, if it is, the challenged submission is sent to Kleros jurors to decide whether it is, or isn’t valid for the list in question. ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-24dac62563c7f0f6f20636603930ae6a3d628dec%2Fimage.png?alt=media) When you submit something to eBay or make a post on Facebook, you don’t need a financial incentive, as those respective companies have plenty of their own to keep that list and its items on point. Facebook moderators are exposed to extreme content and are paid by Facebook to do so. You the user pay Facebook with your personal data which is then in turn used to keep extreme content out of your feed. When there is no centralized actor to do the dirty work, you need some incentivized actors to take over. You just have to follow [a step by step process](https://kleros.gitbook.io/docs/products/curate/kleros-curate-tutorial) where you will be able to define the name of your list, the items that should be accepted and a number of guidelines that community members should follow in the curation process. Curate also offers [many advanced options](https://blog.kleros.io/choosing-parameters-in-kleros-curate/) that give users free rein on how to design their lists. ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-011d3ca97b69b4c837ed51ae7d170d096f6a681d%2Fimage.png?alt=media) Once your list is up, people will be able to submit items and other users will be able to challenge them. Using the List Browser option, you can also see lists created by other people and contribute to them by sending new items or by challenging items submitted by others. 📝 [Direct access to Kleros Curate](https://curate.kleros.io) 📝 {% content-ref url="/pages/-MQvNslA76WtXm7iVQpf" %} [Kleros Curate Tutorial](/products/curate/kleros-curate-tutorial) {% endcontent-ref %} # Kleros Curate Tutorial How to create Token Curated Lists using Kleros Curate ## Let’s Create a List ![](https://blog.kleros.io/content/images/2020/06/Screenshot-2020-06-10-at-17.18.23.png) Upon landing on Curate, you will be greeted with a screen similar to the above. Initially, you will see a list of cards which are each lists of their own. This is the top level (a list of lists if you will) which can be related to the top level ‘Music’ category in the Amazon example. Below music, we had a tree-like structure of subgenres each pertaining to their own list. The first thing we’re going to do is create a list ourselves. This involves deploying two smart contracts (these are the inner logic and workings of the platform) to the Ethereum blockchain. ![](https://blog.kleros.io/content/images/2020/06/Screenshot-2020-06-10-at-17.01.53.png) Click ‘Create a List’ in the header which will direct you to the initial creation page ![](https://blog.kleros.io/content/images/2020/06/Screenshot-2020-06-03-at-15.17.55.png) * **Title** Reasonably self explanatory, the title of your list. To illustrate in the simplest form, I chose something reasonably straightforward in Hiphop Legends. * **Description** A short write up of what your list is about. * **Acceptance Criteria** This field is a critical piece of information for the smooth operation of your list. The Primary Document (or acceptance criteria) is the document specifying what can and can't be accepted to the list. For our example Hip Hop Legends list, the criteria document is as follows: * Accept if Gold or Platinum record selling artist * Accept if famous before 2016 * Accept if > 100k YouTube view on at least one song * **Rejection** * Reject if trap artist * Reject if grime artist * Reject if parody artist * Reject if PG friendly lyrics * **Item name** This is the field in which you would choose the overall name for the items submitted to your list. In our case, an item (or submission) is ‘Hip Hop Legend’ which will be listed in the ‘Hip Hop Legends’ list. The item could be Eminem, Tupac, Snoop Dogg, etc. * **Slider** The slider is the easiest way to set the parameters for your list. If you’re an advanced user, you can follow the instructions below. The cheaper the ETH submission price, the more likely you will see submissions made as it’s less risky to do so. However, it’s also more likely to see malicious submissions due to the cheaper cost of doing so. The opposite is also true for high ETH deposit submissions. The higher they are, the less likely you will receive malicious entries, but fewer submitters may want to take the risk of submissions. If you want to discuss more about this for your list, [contact us here](https://t.me/joinchat/GGUsLhwZj_-aa0SoQTBltA). * **Court & Jurors** Here, you will select which court the challenged submissions from your list will go to be resolved. Each court has differing arbitration costs which are correlated to the difficulty of the case in question. If your list is of high value (see the slider) you may want to choose a higher cost court. If however, it’s a low cost list, you would probably want to use a far cheaper court. For most lists, we recommend using the ‘Curate’ court however, if your list is more complicated, feel free to contact us [here to ask](http://slack.kleros.io/). ### Advanced The advanced parameters are for power users looking to tweak deeper settings within the List builder. If you need more information on these variables, [click here](https://blog.kleros.io/choosing-parameters-in-kleros-curate/) for a detailed overview from our Research Lead, William George. For now, here's a quick overview. * **Item Name** What are the items you are submitting to this list? The example will pertain to certain high performance cars meeting the policy but it could also be a list of decentralized exchanges, the most valuable sneakers or highest valued (in the eyes of the community) crypto projects. * **Submission Deposit** This is the cost for a user to submit an item to your list in ETH. Remember, it’s a deposit stake so they will get it back if the submission is accepted. * **Removal Deposit** It’s possible that submissions make it on that may be subjective, somewhat borderline or adhering to an earlier set of criteria. If that’s the case, users can make an ETH deposit to remove a registered item on the list. Note, the item still has to go through a ‘challenge period’ and is not delisted immediately. It’s possible that jurors will rule that the removal request was not valid meaning the initial user who made it, would lose their deposit. * **Challenge Submission Deposit.** If a user makes a submission to a list that another user doesn’t believe meets the policy criteria, it can be challenged. A high challenge cost could make it less likely that items will be challenged however, a lower challenge cost could mean an increase in ‘bad challenges’. I.e, items that do merit acceptance to the list but are challenged otherwise. * **Challenge Removal Deposit** It is in fact possible to challenge a removal request which can be tweaked in this parameter. As an example: An item that has previously been accepted to the list was subsequently challenged for removal by user A. User B doesn’t think it should be removed from the list and challenges User A. Fill in all the parameters as you want and click next. **Add Your Items** ![](https://blog.kleros.io/content/images/2020/06/Screenshot-2020-06-02-at-12.13.01.png) This screen lets you define your items, or fields that will be used on the list. You can add as many as you need. ![](https://blog.kleros.io/content/images/2020/06/Screenshot-2020-06-02-at-12.14.03.png) Here, we can see only two separate fields were necessary for our simple Hip Hop Legends list. We’ve called the first one ‘Name’, selected it as a text field and set ‘Index’ to on. The index button makes it possible for users to search based on that field. For example: If we submitted a Hip Hop Legend with the name ‘ Eminem’, users can search throughout the whole list just by searching for Eminem. The second field is a simple image field allowing users to add a picture of their legend. ## Badge List Parameters Badges allow your list to specify even more parameters which add ‘badges’ to certain submissions. This can create a tiered system in which an original submission is later ‘upgraded’ in its submission weight with further qualities. As an example, we could add a ‘Grammy’ badge to our Hip Hop Legends list which specifies only submissions (Hiphop Legends) that have Grammy’s can apply for that badge. Another example could be that of a ‘Platinum’ badge which specifies only submissions to list that have platinum selling records are allowed that badge. We'll create a separate explainer for badges but if you want to add them and don't know how, just [ask us on Telegram](http://t.me/kleros). ![](https://blog.kleros.io/content/images/2020/06/Screenshot-2020-06-02-at-12.15.07.png) Once you’ve made it to the final screen, you’re now ready to deploy. You can also go back to previous screens and make sure all the information is correct. ![](https://blog.kleros.io/content/images/2020/06/Screenshot-2020-06-02-at-12.16.06.png) If you’re happy with it, click Deploy! ![](https://blog.kleros.io/content/images/2020/06/Screenshot-2020-06-02-at-12.16.24.png) On doing so, you’ll be asked to pay the contract deployment fees (both for the list and the badges. If you don’t need badges, that list is still available for use at a later date). Once you accept the Metamask transactions and pay the fees, your list will be deployed. ![](https://blog.kleros.io/content/images/2020/06/Screenshot-2020-06-02-at-12.27.49.png) ## Add Your List to The List of Lists The List of Lists homepage. When you click 'Browse' you will instantly be directed to this page. ![](https://blog.kleros.io/content/images/2020/06/Screenshot-2020-06-11-at-17.47.46.png) Once you've created your list it isn't automatically added to our Browser Registry. Your list is still fully usable but won't show up for users visiting the homepage of the Curate site. Submitting your list to the list of lists requires similar actions as submitting an item did earlier. ![](https://blog.kleros.io/content/images/2020/06/Screenshot-2020-06-11-at-20.26.29.png) Add your list to the 'List of lists' by clicking on the 'Submit List' button. You'll need to make a deposit confirming your list fits the criteria in the above image. ![](https://blog.kleros.io/content/images/2020/06/Screenshot-2020-06-11-at-21.36.39.png) If accepted, your list will remain in The Registry indefinitely unless it is challenged at a later date. This may be due to the list going off topic or spammy for example. If a large amount of the listings no longer conform to the policy, that would be a reasonable challenge in this case.The current Curate homescreen showing The Registry (List of Lists) and some pending submissions. ![](https://blog.kleros.io/content/images/2020/06/Screenshot-2020-06-12-at-11.06.54.png) ## Submit ![](https://blog.kleros.io/content/images/2020/06/Screenshot-2020-06-02-at-14.17.21.png) Once your list has been deployed, you are ready to submit items. As you can see in the image above, our list has two submissions. The first is not yet registered and the second has been challenged which replaces the original card with a ‘potentially offensive content’ placeholder which can be revealed by the user. Click ‘Submit Hiphop Legend’ (Remember that ‘Item Name’ field from the list creator? Here it is). ### Make a Submission ![](https://blog.kleros.io/content/images/2020/06/Screenshot-2020-06-03-at-17.39.15.png) A Hip Hop Legend item ready to submit. Notice the deposit required is 0.075ETH. If the listing is accepted, you’ll get that back. If it’s challenged, this deposit is used as part of the collateral used to pay jurors for the arbitration. You win, it’s returned, if you don’t, it’s lost. ### Challenge a Submission ![](https://blog.kleros.io/content/images/2020/06/Screenshot-2020-06-02-at-14.17.57.png) Select the listing you want to challenge and write a description of why you think it doesn’t belong on the list. This information will be sent to Kleros jurors who will make a decision on whether it makes it onto the list or not. ![](https://blog.kleros.io/content/images/2020/06/Screenshot-2020-06-02-at-14.18.37.png) # Kleros Scout A safe, decentralized way to verify whether crypto websites, tokens, or contracts are secure to interact with. 🗄️ [Kleros Scout app](https://app.klerosscout.eth.limo/) 🗄️ ## What Is Kleros Scout? Kleros Scout is an extension of Kleros Curate. The difference? * **Kleros Curate** can verify information about any type of asset (real estate, on-chain assets, stocks, articles, fake news, etc.). Anyone can create new registries with their own rules. * **Kleros Scout** focuses on verifying key information about on-chain assets (such as smart contracts, tokens, and domains) to help users avoid scams and fraudulent activity. Both platforms share the same decentralized mechanism, using crowd intelligence for data verification. As a part of Curate, Kleros Scout is fully decentralized. No central authority controlling or filtering which assets can be included. All its data is transparent and open for anyone to verify. It is entirely run by crowd intelligence. See more about differences in [FAQ](/products/curate/kleros-scout/faqs) ## Why it is Safe Since Scout is part of Curate, it uses the exact same mechanism to ensure safety. #### PREVENTION * **Submitting new entries:** Users must place a deposit. If they provide fraudulent information, they will lose money. * **Challenging submissions** : Similarly, if someone claims an entry is non-compliant, they must place a deposit. If they raise unnecessary or incorrect challenges, they risk losing their deposit. The community verifies submissions and challenges 24/7, also driven by [reward and bounty mechanisms.](/products/curate/kleros-scout/earn-with-kleros-scout) #### DISPUTE RESOLUTION: How Challenges Are Handled Once an item is challenged, it goes directly to the [Kleros Court](/products/court), where impartial jurors analyze evidence and ensure the correct outcome for the submission. ## Why Scout is Important Scams and errors can happen (too) often on blockchain. By using the crowd’s collective knowledge, Kleros Scout helps label or remove suspicious asset information before they can mislead users. * Stops fake tokens, phishing websites, and risky contracts. * No single company controls it. It is fully decentralized. * Suspicious submissions are double-checked using Kleros Court. ## Current registries Kleros Scout currently curates information about the following items: * Address Tags: It certifies the association between public name tags and contract addresses. * [Single tags](https://app.klerosscout.eth.limo/#/?registry=Single_Tags). * [ATQ(Address Tag Query)](https://app.klerosscout.eth.limo/#/?registry=Tags_Queries): A more efficient way to populate the registry. Allows submitters to define ownership of multiple addresses under the same entity via a single submission. * [Contract-Domain Name registry](https://app.klerosscout.eth.limo/#/?registry=CDN) : verified contract-to-domain name pairings. * [Tokens registry](https://app.klerosscout.eth.limo/#/?registry=Tokens) 💡 Remember: Scout shares registries with Kleros Curate, meaning all registries are accessible from both platforms. Scout provides a dedicated experience for on-chain assets. ## How it works: quick-guide This is a quick-use guide, for the full step-by step guide, check [here](/products/curate/kleros-scout/tutorial). **Submitting an Entry** (Example: Listing a Token) 1. Go to[ Kleros ](https://app.klerosscout.eth.limo/#/?registry=Tokens)Scout, Token registry. 2. Check the submission policy of that specific registry. *Registry Details>View* 3. Once you checked the Policy, click “Submit Entry” to submit a new item. 4. Fill the form with required information 5. Press “Submit” and complete the transaction\ *Attention: Make sure your submission complies with the policy, as inconsistent submissions will result in the loss of your deposit.* 6. Wait for the community to approve it! **Challenging a Suspicious Entry** 1. Find a submission that appears to be incorrect (e.g., a token with inaccurate details). 2. Click “Details” and then “Challenge Entry” 3. Provide evidence (e.g., 'This token is not present on this chain') by filling out the dedicated form. 4. Press confirm and deposit the required amount.\ *Attention: Make sure your challenge is valid and backed by evidence, as unsuccessful challenges will result in the loss of your deposit.* 5. Jurors will review the case. If you win, you earn a bounty! For a detailed step-by-step guide: check our full [tutorial ](/products/curate/kleros-scout/tutorial)here ## Who can Use Kleros Scout? * **For Crypto Users**: Avoid scams before interacting with crypto assets (tokens, contracts, websites, etc.). * **For Projects**: Prove your token/contract is safe and verified. * **For Contributors**: Earn crypto while helping maintain a safer ecosystem. Do you know you can earn rewards and bounties by participating in curating listings on Kleros?\ Discover how you can maximize your earnings while helping to build a safer, more trustworthy ecosystem. Check out the details [here](/products/curate/kleros-scout/earn-with-kleros-scout)! ## How to Access Kleros Scout Data? * **Directly Through the Registry:** Browse and verify entries. [Kleros Scout](https://app.klerosscout.eth.limo/) * **Via Partner Platforms:** Scout data is integrated with partner services. Click here for more information. * **MetaMask "Snap" Plug-in**: Access Scout’s verified data directly in your MetaMask wallet.. Learn how to set it up [here](/products/curate/kleros-scout/kleros-scout-metamask-snaps).

On the left, how Kleros Curate information are displayed on Etherscan. On the right, how you will see insights in real time directly on your Metamask wallet with Scout Snap!

💡 Do you have a dApp and want to integrate Kleros Scout data? Contact us!
# Tutorial This section gives you a complete walk-through on how to use Kleros Scout. ## A. Submitting a New Entry 1. Visit [Kleros Scout](https://app.klerosscout.eth.limo/) Dapp * Go to the [Kleros Scout](https://app.klerosscout.eth.limo/) Dapp. * Select the relevant registry (e.g., Tokens registry, Address Tags registry, Contract-Domain registry). 2. Check Policy for Submission Requirements. * Each registry has its own rules. Read them carefully (e.g., you might need to provide a website link for verification or proof of an audit). You can find them by pressing the "Registry Details" button. * Gather all the information, links, screenshots, and documents requested by the policy. 3. Start the submission process. * Press the “Submit entry” button. * Fill out the form with accurate information (contract address, project name, etc.) that you collected in the previous step. * Upload any evidence (e.g., audit PDFs or official website links), if required. 4. Pay the Deposit and Submit * You will need to deposit some xDai (or another token, depending on the registry). * Make sure you have enough funds. * Complete the transaction. Once confirmed, your entry is officially Submitted and in "Registration Requested" status. *Tip: Always double-check facts before submitting. If your submission is incorrect, you lose your deposit.* 5. Wait for the Challenge Period * While in "Registration Requested" status, other users can challenge your entry if they see any errors. * If no one challenges it during the set period, your entry will be included in the registry. * If the entry is challenged, refer to [point C ](#c.-the-submission-is-in-challenged-status)on this page. ## B. Challenging a submitted entry 1. Identify a suspicious entry currently in 'Registration Requested' status. * Browse the registry to see newly submitted and questionable entries. * Double-check entry information and compare it with the policy requirements. * If you find evidence that it’s false, you can challenge it. 2. Gather Evidence * Collect links, screenshots, or any documents proving the submission is invalid. 3. Challenge the submission * Once you have collected all the evidence, select the incorrect entry by pressing the 'Details' button. * Then, press the “Challenge Entry” button to start the challenge.\ *Make sure you challenge the correct entry!* * Fill the challenge form in the most detailed way possible. Remember: this step is crucial, as your evidence will be analyzed by the Court. Ensure you provide relevant information * Make sure you have enough funds in the selected token. * Press “confirm” to complete the transaction in your wallet. 4. Now the submission is in 'Challenged' status and it will be resolved via [Kleros Court](/products/court) * Check the [Dedicated section](#c.-the-submission-is-in-challenged-status) to see what to do * Jurors review both sides. 1. If they rule in your favor, you get a reward. 2. If they rule against you, you lose your deposit. For detailed instructions on what to do when an entry enters challenge status, refer to the next section. ## C. The submission is in Challenged status. This part of the tutorial is valid for both the submitter and challenger. 1. Monitor the Submission Status: * Once an entry is marked as “Challenged,” ensure you stay updated. * Whether you are the submitter or the challenger, be ready to provide strong, relevant evidence to support your case. 2. Where can I add more evidence? * When selecting the challenged entry, select the challenged entry and you will see a "Submit Evidence" button. * Click it, and you’ll see a form where you can upload additional documents, links, or screenshots. 3. Keep monitoring evidence updates and the dispute deadline. * Your counterpart may submit more evidence against you. * Ensure your arguments are solid and backed by verifiable information. 4. Deadline * Once the deadline is reached, jurors will make their decision. 5. Dispute has been resolved * Remember: the final ruling of the dispute can always be appealed if you believe the jurors made an incorrect decision. * To check how to appeal cases go to [Kleros Court](/products/court) and follow the procedure ## D. Removing a Confirmed Entry Some projects or contracts may initially seem legitimate but engage in fraudulent behavior after being listed. Even if an entry has been accepted and is part of the registry, it can still be removed if fraudulent activity is later detected . The registry is designed to remain a safe place and provide ongoing protection. Steps to Remove a Fraudulent Entry: 1. Select the Relevant Registry: * Navigate to the registry containing the entry in question. 2. Locate the Entry: * Find the already included entry that you suspect of being fraudulent. * Select it by pressing "Details" button. 3. Compare the Entry with the Policy: * Check if it still meets the registry’s rules * If discrepancies exist, start gathering evidence. 4. Submit a Removal Request: * Once you have enough proof, press the "Remove Entry" button. * Fill out the challenge form with as much evidence as possible. 5. Provide Strong Evidence: * Your submission will be reviewed by the Court, so accuracy is critical. * Ensure you submit complete and clear information. 6. Complete the Transaction: * Make sure you have enough funds in the required token for the challenge deposit. * Press 'Confirm' to submit your challenge through your wallet. 7. Removal Request status * The entry is now in 'Removal Request' status. If the community supports your removal request, the entry will be removed from the registry. * If the community disagrees with your request, they will challenge the removal. 8. Refer to [point C](#c.-the-submission-is-in-challenged-status) for detailed instructions on what to do in case of a challenge.
# Earn With Kleros Scout Kleros Scout incentivizes contributors to maintain accurate registries. You can earn rewards both by adding new items to the list and by verifying assets submitted by other users. ## 1. Challenges: Earn Bounties by detecting erroneous entries * Submitters must deposit funds (e.g., xDai) to list an entry (e.g., a token). * If you find an invalid or malicious submission that doesn’t comply with the registry policy, you can challenge it by staking a deposit and escalating it to Kleros Court. * If jurors rule in your favor, you will earn a portion of the submitter’s deposit as a bounty. 💡 Example: Challenge a token that falsely claims to have an audit and earn a reward.\ 🔗 Check the guide on how to challenge an entry \[[here](/products/curate/kleros-scout/tutorial)]. ⚠️Risk Note: Incorrect challenges will result in the loss of your deposit. ## 2. Reward Programs: Earn rewards by adding new entries * Periodic Incentives: Kleros and partner projects run campaigns to reward contributors for adding high-quality entries (e.g., submitting tokens or contracts on specific chains). * How to Participate: * Check active campaigns on the [Kleros Blog](https://blog.kleros.io/) or through[ Kleros ](https://klerosscout.eth.limo/)[Scout](https://klerosscout.eth.limo/) interface 🔗 Check the guide on how to submit new entries \[[here](/products/curate/kleros-scout/tutorial)]. # Partnerships Just as anyone can submit, verify, and challenge entries, anyone can retrieve and integrate data from Scout registries into their platforms. Many of the most important Web3 partners already use data from Kleros Scout, recognizing the value of fully decentralized and permissionless data curation, and supporting a safer blockchain ecosystem.
## Why Integrate data from Kleros Scout? **User Confidence:** Verified contract data helps users feel secure when interacting with assets on your platform. **Improved Conversion Rates:** When users see real-time, verifiable insights, they feel reassured. This extra layer of confidence makes them more likely to complete transactions. **Clear Verification Process:** Data comes directly from decentralized, on-chain sources, ensuring accuracy and tamper-proof information. Users can check how an item was verified **Protect Users from Scams**: Displaying verified contract security data can help prevent scams, phishing, and fraudulent transactions. **Reduce Legal Risks** :Publicly showing verified information demonstrates due diligence, reducing liability for hosting fraudulent assets. **Lightweight & Easy to Integrate** :Kleros Scout data can be displayed effortlessly without disrupting platform operations. ## How to integrate Kleros Scout data into your platform? Partners like Ledger and Etherscan directly display Scout data on their platforms. In partnership with MetaMask, we developed a dedicated plugin that provides real-time information about the specific contract or address during the transaction, directly in MetaMask wallet. Check the[ dedicated section ](/products/curate/kleros-scout/kleros-scout-metamask-snaps)to learn how to use it!

On the left, how Kleros Curate information are displayed on Etherscan. On the right, how you will see insights in real time directly on your Metamask wallet with Scout Snap!

## Want Scout Data in Your App? Check our dedicated section [here](/integrations/types-of-integrations/2.-curated-data-integration-plan), or Message us on [Telegram](https://t.me/kleros) \ \
# Kleros Scout - Metamask Snaps Empowering safe dApp interactions with community curated and secured data. Started in 2019 with the Tokens registry, [Kleros](https://kleros.io/?ref=blog.kleros.io) has been a pioneer in curating decentralised registries, especially around security metadata. We now introduce Kleros Scout, a [Metamask Snap](https://metamask.io/snaps/) designed to enable safe contract interactions by providing insights, curated and secured by the community!

The Kleros Scout plugin in action.

The Kleros Scout Snap utilises information from the following Kleros Curate registries: * [**Address Tags registry**](https://curate.kleros.io/tcr/100/0x66260C69d03837016d88c9877e61e08Ef74C59F2) of verified project and name tag of contracts * [**Contract-Domain Name registry**](https://curate.kleros.io/tcr/100/0x957A53A994860BE4750810131d9c876b2f52d6E1) of verified contract-to-domain name pairings * [**Tokens registry**](https://curate.kleros.io/tcr/100/0xeE1502e29795Ef6C2D60F8D7120596abE3baD990) of ERC-20 tokens Install the Kleros Scout Plugin on the [**official Metamask Snaps Directory**](https://snaps.metamask.io/snap/npm/kleros/scout-snap/) today! ## 1. How can I install the Kleros Scout Snap? Step 1: Install [Metamask Flask](https://metamask.io/flask/) Step 2: Head to Step 3: Search for ***@kleros/scout-snap***
Step 4: Install ***@kleros/scout-snap**!* It’s that easy :) ## 2. How to use the Snap's features? Once you install the Kleros Scout Snap, with every txn/contract interaction, you will see a tab which provides you with insights around the same. Upon installation, If you see this, you are already using community curated contract insights for secure dapp interaction - the most important feature of the Kleros Scout Snap.
## 3. What does the Kleros Scout Snap do? This Snap pulls contract metadata from Kleros's decentralized token curated registries (TCRs) to provide insights around the contract you are interacting with. ## 4. What does the Snap not do? The Kleros Scout snap **does not**: → Endorse any contract interaction → Do any centralised whitelisting - all data is community curated. To know more about the same, go to ‘How is the registry data curated?’. *→* Guarantee 100% accuracy or take on any liability caused as a result of an insight. ## 5. What decentralised registries by Kleros are used for this Snap? The data used in this Snap is pulled from the following decentralised registries on Kleros Curate: * [Contract-Domain Name Registry](https://curate.kleros.io/tcr/100/0x957a53a994860be4750810131d9c876b2f52d6e1) * [Address Tags Registry](https://curate.kleros.io/tcr/100/0x66260c69d03837016d88c9877e61e08ef74c59f2) * [Tokens Registry](https://curate.kleros.io/tcr/100/0x70533554fe5c17caf77fe530f77eab933b92af60) [You can read more about these registries and their capabilities here.](https://blog.kleros.io/migrating-kleros-registries-to-v2/) ## 6. How can I reach out for Snap support? You can either drop in a message on our [TG support group here](http://t.me/KlerosCurate) or [email us here](mailto:support@kleros.io)! We generally get back within 24-48hrs. # Knowledge Base Guide for addressing common questions from users during the course of using the Kleros Scout Snap. ## **How is the data for providing contract information via the Kleros Scout Snap curated?** **Kleros Curate** is a decentralized dApp that can be used to create open curated registries of just about anything using financial incentives and Kleros dispute resolution technology to ensure a list stays on topic and that each entry is compliant to the predefined acceptance criteria. For the Kleros Scout Snap, we are focused on contract insights data (security data) to secure dApp interactions. ## **Who submits and decides if an entry stays on the list?** When a user (anybody can make a submission as long as they can put up a deposit along with it) submits an item to Curate, it is first vetted by a challenge period which allows anyone else to challenge that submission (anybody from the community who can put up a competing deposit is a challenger). If the submission isn’t challenged within this period of time, it’s deemed legitimate and on topic, if it is, the challenged submission is sent to Kleros jurors to decide whether it is, or isn’t valid for the list in question. ## **What is the need for a credibly neutral, community sourced contract information data source?** There is an inherent vested interest for centralised parties to whitelist new tokens for example, in order to make a profit through the volume/liquidity increase in the market for that token due to the listing. This has happened in the past with several CEXs. Similar issues plague centralised address tagging and contract to domain mappings (phishing attacks, front-end DNS attacks, etc.) The need for decentralised, community sourced and secured security metadata can’t be overstated. ## **I’m seeing that some of my contract interactions don’t have any insights. Can I make submissions to the Kleros security metadata registries?** Absolutely! We encourage the community to submit and police submissions to move towards a scaled, highly secure, community driven data source which can empower safe dApp interactions. [Here are step-by-step guides to make submissions to the 3 security metadata registries.](https://blog.kleros.io/how-to-submitting-to-the-security-metadata-registries-on-kleros-curate/) ## **Why will I take on the risk of interacting with an unknown contract and submit an entry to the Kleros registries?** There are two important reasons for this: * 💰 ***Kleros’ Incentives Programs:*** To encourage community submissions to scale and cover the long-tail of security data on the registries, Kleros regularly runs incentives programs. We have seen regular submitters win hundreds of $$ by simply helping secure the community’s dApp interactions. [You can see information about the latest incentives program here.](https://blog.kleros.io/incentives-program-for-security-registries/) * 👫 ***Altruism:*** There is little to no risk involved with making a submission to the registries of a contract you have previously interacted with, which you know is safe. You are enabling thousands, if not more people to have peaceful, anxiety free contract interactions. # FAQs ## What is the difference between Kleros Curate and Kleros Scout? Kleros Scout is a specialized branch of Kleros Curate. * Kleros Curate can be used to verify all types of assets, including real-world assets, traditional finance (TradFi), real-estates, stocks and more. Partners can integrate Curate with their own rules and policies. * Kleros Scout is fully focused on decentralized verification of on-chain assets like smart contracts, tokens, and domains ## I see the same entries on both Kleros Scout and Kleros Curate. Is this normal? Yes, this is completely normal. Kleros Scout retrieves data from Kleros [Curate](https://curate.kleros.io/), but focuses only on selected registries related to Web3 instruments.\ On these selected registries, you can interact with entries from either platform, depending on your preference. ## **Is Kleros Scout free to use?** Browsing and verifying entries is completely free. However, submitting or challenging entries requires staking a deposit. This deposit discourages spam and ensures high-quality participation. If your submission is valid or your challenge succeeds, you get your deposit back. ## **I discovered fraudulent activity from an entry that is already included in one of the registries. Can I remove this entry from Kleros Scout?** Yes! Even accepted entries can be removed if they later become fraudulent or non-compliant. To request removal: * Gather evidence proving the entry no longer meets the registry's rules. * Submit a removal request via the registry interface. * If challenged, the case may go to Kleros Court for final decision. See the full guide [here](/products/curate/kleros-scout/tutorial) ## **Can I earn rewards by participating in Kleros Scout?** Yes! You can earn in two ways: * Adding new entries – Some registries have reward programs that pay for high-quality submissions. * Challenging incorrect entries – If you successfully challenge a fraudulent entry, you earn a portion of the submitter's deposit as a bounty. Here you find the complete [guide](/products/curate/kleros-scout/earn-with-kleros-scout). \ Stay updated and Check the Kleros Scout interface or [Kleros Curate blog ](https://blog.kleros.io/)for active reward programs.
# Enterprise Easily integrate Kleros’s “justice as a service” into your institution—without the complexities of managing cryptocurrency.
How is Kleros different from other Dispute Resolution Methods? Thanks to its innovative mechanism, Kleros has the potential to be more efficient than traditional courts or arbitration. It uses blockchain for transparency and automation, and relies on crowdsourced decision-making: disputes are resolved by randomly selected jurors from a decentralized pool, who apply clear rules and vote independently. This use of collective intelligence enables Kleros to scale to a high volume of cases while keeping costs low for the parties involved.
What types of disputes is Kleros best suited for? Kleros is a natural fit for Web3 and DAO ecosystems. It allows decentralized communities to resolve disputes without centralized intermediaries, with decisions enforced automatically by smart contracts. This makes it particularly useful for use cases like protocol governance, on-chain moderation, oracle disputes, and enforcement of rules in decentralized platforms. It’s also well suited for “real world” disputes, specially those that are high in volume and low to medium in value, such as e-commerce, freelance work, insurance claims, or consumer complaints, where other dispute resolution mechanisms might be too slow or expensive. Kleros provides a faster and more cost-effective alternative while still ensuring fairness and procedural integrity.
What does "Enterprise" mean in the context of Kleros? In Kleros, "Enterprise" refers to the use of Kleros’ dispute resolution technology by companies, institutions, or governments to resolve disputes within their own platforms or services. The key difference is that the complexity of blockchain is abstracted away—neither the organization nor its users need to handle crypto or interact directly with smart contracts.
Why should companies use Kleros? Integrating Kleros gives companies a fast, affordable, and transparent way to resolve consumer disputes—without the need for lengthy and expensive legal processes. By offering users a fair dispute resolution option, companies can increase trust and user retention, while reducing legal costs. It also shows commitment to fairness and user protection, which enhances brand reputation and loyalty.
Why should governments use Kleros? By integrating Kleros, governments can expand access to justice with a scalable, low-cost, and transparent online dispute resolution system. This is especially valuable in addressing the growing number of claims—speciallly in consumer protection—and the limited capacity of traditional courts. Kleros helps ease the load on overburdened judicial systems and ensures faster, fairer outcomes for citizens, while promoting innovation in public service delivery.
Has Kleros been used to resolve real world disputes? Yes. Kleros has already been adopted for real-world use cases. For example: * **MetLife Mexico:** One of the world’s leading insurance companies is using Kleros to resolve actual insurance-related disputes in a controlled pilot in México. * **Lemon Cash:** with +3 million users, the Latin American Fintech company uses Kleros to resolve consumer complaints. More than 100 cases were resolved in Kleros. * **Mendoza Supreme Court (Argentina):** A groundbreaking pilot was launched with the judiciary to explore the use of Kleros in small claims consumer and neighbourhood disputes. * [**Maldo.uy**](http://Maldo.uy)**:** an online p2p services marketplace uses Kleros to resolve disputes between independent service providers and their clients.
How does Kleros ensure procedural fairness? Kleros enforces procedural fairness by embedding core principles of due process and constitutional rights into its system design: * **Clear rules and equal treatment:** Every case is governed by transparent policies that are publicly available and applied equally to both parties. This ensures consistency and predictability in decisions. * **Predefined and immutable procedures:** The procedural framework—such as deadlines, evidence stages, voting periods, and appeal windows—is fixed in advance by smart contracts. Thanks to the immutable nature of blockchain, these procedural rules cannot be secretly altered or manipulated, ensuring integrity, predictability, and protection against due process violations. * **Right to be heard:** All parties have the opportunity to present their case. Because Kleros is open and decentralized, no central authority can block or prevent access to the system. They can submit any type of digital evidence—documents, images, expert reports, web links, or even video testimony—ensuring broad access to procedural participation. * **Notice and transparency:** Parties receive timely notifications (e.g. email alerts) when a dispute is initiated. In peer-to-peer contracts, this is reinforced by arbitration clauses that define how and when notice must be given. * **Independence and impartiality:** Jurors are randomly selected from a large pool, significantly reducing bias or collusion. Their financial incentives are aligned with honest and coherent decision-making: jurors who vote contrary to the majority without proper justification may lose stake, while those who follow the best interpretation of the rules are rewarded. * **Right to a reasoned decision:** In some cases, jurors have additional economic incentives to properly justify their votes based on the evidence and the applicable policy, reinforcing the quality and legitimacy of decisions. * **Right to appeal:** If a party believes the outcome was flawed, they can appeal to a higher court composed of more jurors, adding procedural layers and enhancing the review process—similar to appellate safeguards in traditional systems. * **Access to justice and cost-efficiency:** Kleros removes many procedural and financial barriers typical of traditional legal systems, offering fast, low-cost, and accessible justice—particularly for low-value or digital-native disputes that courts often overlook. These mechanisms allow Kleros to uphold core legal principles such as due process, impartiality, legal certainty, and the right to a fair hearing—making it compatible with constitutional principles across jurisdictions.
What is the compliance rate for Kleros decisions? For “Enterprise” disputes, companies voluntarily and explicitly agree to be bound by Kleros’ decisions. This constitutes a contractual obligation toward their users (and even us), which we require as a condition for integration. To date, we have not encountered any instance of a company refusing to comply with a Kleros ruling. However, if such non-compliance were to occur, the user would retain all available legal remedies, including the option to bring the matter before a court. Additionally, the company would face significant reputational damage for failing to honor a process it voluntarily agreed to uphold. If you want to know more about these types of integrations, [here](https://www.google.com/url?q=https://wiki.lemon.me/es-ar/institucional/justicia-descentralizada-en-lemon\&source=gmail\&sa=D\&sa=E).
Can Kleros decisions be recognized as arbitral awards? Yes. Kleros produces decisions that could be recognized as arbitral awards as long as the arbitral clause is properly written and the process is designed to respect key elements required by applicable arbitration law. In most cases, countries have adopted the [UNCITRAL](https://uncitral.un.org/en/texts/arbitration/modellaw/commercial_arbitration/status?utm_source=chatgpt.com) Model Law on International Commercial Arbitration, which provides flexibility and allows parties to freely choose their arbitration procedure. This means that parties could agree, within their arbitration agreement, to use Kleros as their dispute resolution mechanism. For deeper analysis, see [this thesis](https://www.google.com/url?q=https://cdn.kleros.link/ipfs/QmWqmoEXcmKHgeKX3NUk9mMRssZymUj9sYQSQ3vvxTiyDA\&source=gmail\&sa=D\&sa=E) explaining how Kleros decisions can be recognized and enforced as foreign arbitral awards under the New York Convention. In a landmark [case](https://cdn.kleros.link/ipfs/QmRNyeRQVpfP4xovAdZBjYQ3TrYFJP3YKjEKUoMLSnoXnH/Mauricio%20Virues%20Carrera%20-%20Reporte%20del%20Kleros%20Fellowship%20of%20Justice.pdf) in Mexico, a Kleros jury's decision was recognized and enforced as an arbitral award. This case used a hybrid approach where an identified arbitrator was selected and adopted Kleros sustantive ruling in a formal arbitration award.
What about jurisdictions where written arbitral awards are required to be signed and issued by identified adjudicators? If the applicable law requires a signature from the arbitrator, and the legal framework recognizes the equivalence of digital signatures to physical ones, one could reasonably argue that Kleros awards are indeed “signed” by the arbitrators. This is because each juror must execute and sign a blockchain transaction to cast their vote, and this signature is cryptographically linked to the juror's unique account, ensuring authenticity and non-repudiation. Regarding anonymity, if the legal system or arbitration rules require identifiable arbitrators, there are mechanisms available to meet that standard. The V2 version of Kleros courts allows configuration to whitelist and grant access only to jurors who meet specific criteria, for example, those who have completed an identity verification process and fulfill qualification requirements (such as being licensed lawyers). This ensures that the identity of each juror is known or can be verified. For more ingormation, please refer to [this paper](https://www.google.com/url?q=https://cdn.kleros.link/ipfs/QmWqmoEXcmKHgeKX3NUk9mMRssZymUj9sYQSQ3vvxTiyDA\&source=gmail\&sa=D\&sa=E).
Can Kleros be used under dispute resolution schemes other than arbitration? Yes. Beyond arbitration, Kleros can also serve in other dispute resolution roles: * **Mediation:** The designated mediator can leverage Kleros platform to provide faster dispute resolution. The mediator helps parties prepare their binary position documents for Kleros, and submits them to Kleros. After the Kleros decision, the mediator helps ABC and XYZ incorporate the decision into a Master Settlement Agreement (MSA), which is enforceable under the 2019 Singapore Convention on Mediation. In this way, the hybrid model allows a complex construction dispute to be broken down into separate issues and independently resolved, which may not only lead to a faster resolution, but also a more satisfying and fair outcome for both parties. For more details, see [this research paper](https://blog.kleros.io/innovating-dispute-resolution-a-cohesive-approach-blending-traditional-mediation-and-kleros-blockchain-arbitration/). * **Consumer Ombudsman:** Kleros can act as a decentralized consumer ombudsman, where consumers submit disputes about products or services and jurors evaluate claims fairly and transparently. We are currently piloting this approach in Argentina, enabling consumers to resolve conflicts faster, and without costly litigation for the Company. * **Consultative layer:** Kleros can provide non-binding expert or common citizens opinions to assist judges or authorities in their decision-making, acting as a consultative body. The [Supreme Court of Mendoza](https://blog.kleros.io/kleros-y-el-poder-judicial-de-mendoza-pioneros-en-justicia-descentralizada/), a province in Argentina, has integrated Kleros as an auxiliary tool in its judicial decision-making process. * **Other ADR schemes:** In 2024, Mexico passed a law recognizing decentralized justice systems as valid alternative dispute resolution methods. Under this law, resolutions from Kleros can be final and enforceable if parties agree beforehand.
What are the main institutional obstacles that prevent Kleros decisions from being recognized or enforced by national legal systems? The main obstacle is a lack of familiarity and legal precedent. Kleros decisions, when supported by a valid arbitration agreement and a properly designed process, can meet the standards of international arbitration under frameworks like the UNCITRAL Model Law, which gives parties broad freedom to define procedural rules. Judicial skepticism often stems from the system’s decentralized and pseudonymous nature, but as new generations of judges and regulators emerge, and as government collaborations expand, this resistance is likely to diminish. Kleros is actively engaging with governments to foster understanding and open pathways to formal recognition.
What’s the vision of Kleros for the next years? Kleros is already making strides: it was recognized as a valid alternative dispute resolution (ADR) mechanism in Mexico, we have signed the first-of-its-kind agreement with Mendoza’s Supreme Court, and important traditional companies are benign to use Kleros to solve disputes with their users. Over the next 5-10 years, Kleros may become a widely recognized layer for digital and low-value dispute resolution, both in Web3 and in real-world sectors like insurance, consumer protection, and public administration.
# Oracle Crowd-sourced on-chain smart contract oracle system in collaboration with Reality.eth Kleros Oracle is a product that combines Kleros's dispute resolution system with [Reality.eth](https://reality.eth.link/)'s cryptoeconomic mechanism for verifying real world events on-chain, to deliver a subjective oracle solution able to answer absolutely any question with a publicly verifiable answer. It falls under the category of optimistic oracle solutions, allowing dApps to very quickly arrive at answers or information unless there is a dispute. ## How does it work? Anyone (individual or dApp) can submit a question to the [Reality.eth](https://reality.eth.link/) platform while specifying Kleros as the final arbitrator. For example: * Who won the gold medal in the individual kata category in the Karate World Championship in 2004? * In which month and year was the first version of the game ‘*The Curse of Monkey Island*’ released? In order to create the right incentives, when answering the question, users are required to **post a bond**. If other users believe that the answer is wrong, they can challenge it by doubling the bond and providing a new answer. After each answer, a countdown period begins during which others can submit a different answer. When the countdown period expires, the last person to have posted an answer receives the bond, as well as the reward posted by the asker. Through this bond escalation mechanism, most questions will rapidly get an answer when no different answer is submitted. However, at any point of the answering process in Reality.eth (or when the maximum bond is reached), anyone can "apply for arbitration" to bring in Kleros as an external arbitrator to resolve what the right answer is. Kleros will either confirm the current answer (in which case, the party who provided the final answer receives the bond) or it will provide a different answer (in which case, the new answer is considered definitive and the party who paid the arbitration fees receives the bond). {% content-ref url="/pages/0fpJTEzgoVb5Qeadze5p" %} [3. Kleros Oracle integration](/integrations/types-of-integrations/3.-kleros-oracle-integration) {% endcontent-ref %} # Governor Decentralise DAO governance control securely Kleros Governor is a smart contract that allows for the effecting of DAO governance decisions to be decentralized without compromising security. By designating Kleros Governor as the governor contract for your DAO, batches of transactions representing governance decisions can be submitted as lists to Kleros Governor. In case of disputes about the validity of the submitted transactions, Kleros's jury network will step in to arbitrate the dispute. ## How does it work? The first step to using Kleros Governor is to point to it as the governor contract for your DAO. Each Governor session enforces governance decisions that were passed prior to the start of the current session, which can be organised on a platform like [Snapshot](https://snapshot.org/). Once a decision has been reached, a (technically inclined) user then needs to translate the decision into a list of transactions and submit them for execution by the governor contract. If there is only one list submitted in the challenge period, it will be accepted and the deposit is returned to the submitter. If a competing list is submitted in the same session, a dispute will be automatically created in Kleros Court, and jurors will get to choose which list is correct. After dispute resolution concludes, the deposit from the losing list will be used to pay the jurors and reward the user that submitted the winning list. Lists that most completely enforce the greatest number of governance decisions will be accepted. The process for choosing between lists can be seen [here](https://cdn.kleros.link/ipfs/QmPt2oTHCYZYUShuLxiK4QWH6sXPHjvgXTqMDpCShKogQY/KlerosGovernorPrimaryDocument.pdf). 🏛 [Kleros Governor App](https://governor.kleros.io/) 🏛 # Escrow Secure your on-chain transactions with an Escrow Dapp backed by Kleros dispute resolution 🤝🏼 [Kleros Escrow App](https://escrow-v1.kleros.builders/) 🤝🏼 [⚙️ ETH Escrow Contract](https://github.com/kleros/kleros-interaction/blob/master/contracts/standard/arbitration/MultipleArbitrableTransaction.sol) | [⚙️ ERC20 Escrow Contract](https://github.com/kleros/kleros-interaction/blob/master/contracts/standard/arbitration/MultipleArbitrableTokenTransaction.sol) **Kleros Escrow** is a secure and decentralized escrow Dapp that can be used for any exchange of goods, assets, or services involving an Ethereum-based asset. Using Kleros Escrow, you can transact in the blockchain ecosystem for services, products, and assets with a simple solution that provides a level of trust not yet known outside the traditional commerce space. If a dispute happens, it will be adjudicated by crowdsourced jurors selected and incentivized by the Kleros protocol.
Whether you're a marketing company looking to offer trust to your clients by providing high-quality advertising services backed with dispute resolution, or a freelancer seeking payment protection for your work, Kleros Escrow provides the solution. Both parties can benefit from a non-biased smart contract that securely holds funds. Service providers can deliver services knowing that funds have been deposited in escrow. Conversely, buyers can agree to deals knowing that if the service is not delivered as promised, they have recourse to dispute resolution. ## The Problem solved by Kleros Escrow Anyone who's worked in the crypto ecosystem will be aware of the huge amount of services promoted daily. Whether through Telegram, email, or LinkedIn, you are likely to receive multiple unsolicited offers each day. How to sort the good from the bad, how to add trust to these potentially great marketing deals? These offers range from simple content creation or reviews of your project, all the way to expensive exchange listing offers. In between, there's a plethora of other services including freelancing work, community management, bounty programs, and development work. One key mechanism has been mostly absent from this sector: > A trust backed escrow system to weed out the scammers from the legitimate offerings. The blockchain ecosphere still lacks adequate decentralized dispute resolution processes. In turn, there are many projects who cater to their own arbitration needs using centralized procedures but these don't fit the decentralized ethos nor bring a true unbiased resolution to a disputed case. Kleros aims to change that by using crowdsourced jurors to adjudicate common disputes that happen on the Internet. > Employing a trust-backed escrow platform is a win-win situation: > > * Creates higher sales conversions for companies > * Offers higher quality services and protection to consumers > * Provides fair, decentralized dispute resolution when agreements break down > * Eliminates the need for trusted third parties in transactions # Kleros Escrow Tutorial **Kleros Escrow** is a secure and decentralized escrow Dapp that can be used for any exchange of goods, assets, or services involving an Ethereum-based asset. Using Kleros Escrow, you can transact in the blockchain ecosystem for services, products, and assets with a simple solution that provides a level of trust not yet known outside the traditional commerce space. If a dispute happens, it will be adjudicated by crowdsourced jurors selected and incentivized by the Kleros protocol.
## TUTORIAL (One tab for each step) {% tabs %} {% tab title="1/ Initiating a Payment" %} To start an Escrow transaction, you will need to connect your wallet and initiate a new payment. ### 1/ Initiating a Payment #### 1.a. Go to the Kleros Escrow Website Visit [Kleros Escrow V1](https://escrow-v1.kleros.builders/) You will need to connect your Rabby, Metamask wallet or WalletConnect to use the Escrow service.
Once you have connected your wallet to the app (the wallet will ask you to confirm the connection), you will need to ensure you have some Ether (ETH) loaded in the wallet to: * Interact with the Ethereum blockchain (pays transaction fees) * Pay for the Escrow transaction you'll be setting up You should now be able to see the homepage.
The homepage allows you to: * Create new escrowed transactions * Search existing transactions by title or address * Review existing transactions {% hint style="info" %} **INFO**\ **If you already had some escrowed transactions in progress, they will be displayed on the homepage.** {% endhint %} #### 1.b. Create a new Payment * To start configuring an escrowed payment, click on the **"Create Transaction"** button on the top right.
**IMPORTANT:** When you create a transaction, you will be the person who deposits funds into the escrow smart contract. The funds will be held securely until: * You manually release them to the receiver * The receiver manually refunds them to you * A dispute is raised and resolved by Kleros Court * The expiry date passes and either party can execute the transaction The receiver will be able to view and interact with the transaction using their wallet address once you've created it. #### 1.c. Select an Escrow Type * On creating a new transaction you'll get an option to select the type of Escrow transaction you want to create. Select one and click on "Next".
{% hint style="info" %} **TYPES OF ESCROW TRANSACTIONS** **Cryptocurrency Transaction** * Select this option if you want to trade or exchange a crypto asset for another crypto asset * Especially useful where one of the assets is on a blockchain other than Ethereum * Example: Trading ETH on Ethereum for SOL tokens on Solana **General Service Transaction** * Select this when paying for any other type of general service * Allows you to specify your own terms for the agreement * Allows you to upload a document when creating the payment {% endhint %} {% endtab %} {% tab title="2/ Submitting Payment" %} In this step, you will specify the details of the Escrow transaction to be made between parties and lock the funds in the Escrow. ### 2/ Submitting a Payment #### 2.a. **Transaction Details** When creating a payment, you'll be asked to fill out a form providing basic information about the payment: **Required Information:** * **Title for the transaction** * Examples: "Marketing Mission with John D.", "ETH to SOL trade", "Physical NFT delivery" * **Ethereum address for the funds receiver** * The wallet address that will receive the funds when the transaction completes * **Amount and unit** of ETH or ERC-20 tokens to be paid
{% hint style="info" %} **Note:** The transaction details form is the same for both General Service and Cryptocurrecny Transaction types. The only difference between the two transaction types is which Kleros Court will handle disputes if they raise. Cryptocurrency Transaction cases will be handled by Kleros Blockchain Non Technical Court whereas those under General Service will be handled by Kleros General Court. {% endhint %} **Selecting ERC-20 Tokens:**\ If you wish to pay with an ERC-20 token, click on the asset dropdown to select another asset. The default tokens displayed are ETH and PNK. To use a different ERC-20 token, enter the token's contract address in the "Add custom token" field (available from the Etherscan token contract page) and click "Add token."\ \ {% hint style="info" %} ⚠️ **WARNING:** As noted in the interface, non-standard ERC-20 tokens such as USDT, BNB, and OMG are **not supported** by Kleros Escrow V1. {% endhint %} #### 2.b. Setting the Delivery Deadline (Terms Step) In the Terms step, you will set the timeline for your escrow: **Description:** Enter a detailed description of the service or product to be delivered. This description is important as it will be used by jurors if a dispute arises. **Delivery Deadline (Local time):** Select the date and time by which the receiver should deliver the service or product. This is the only timeline you need to set.
**Understanding How the Timeline Works:** All Kleros Escrow V1 transactions follow an automatic timeline: 1. **Service Period**: From creation until the delivery deadline * The receiver should complete and deliver the service/product during this time * Either party can manually release/refund or raise a dispute at any time 2. **Buffer Period**: Automatically set to 7 days after the delivery deadline * Additional time window where either party can review and raise a dispute * Provides a grace period before automatic execution 3. **Escrow Expiry**: Automatically occurs 7 days after the delivery deadline * After this date, either party can execute the transaction (releasing funds to receiver) **IMPORTANT:** * The buffer period is **fixed at 7 days** and cannot be changed * The escrow expiry date is automatically calculated as: Delivery Deadline + 7 days * You will see both dates displayed after creating the transaction **Example Timeline:** * Transaction created: December 17, 2025 * Delivery deadline set to: January 16, 2026 * Escrow expiry (automatic): January 23, 2026 This means: * Receiver should deliver by January 16 * You have until January 23 to review and raise any disputes * After January, either party can execute the transaction to release funds to receiver #### 2.c. Agreement Document **Upload an Agreement PDF (optional):** You can upload a PDF document detailing the specifics of the agreement between the parties. Alternatively, you can include all terms in the Description field. **IMPORTANT:** The Description and/or Agreement PDF is crucial and will be relied upon by jurors in the event of a dispute. Try to clearly specify: * The parties involved * The nature of the service/good expected * Specific deliverables or milestones * Acceptance criteria * Any conditions of the engagement #### 2.d. Submit Transaction Once all the details are filled in: 1. Review all information in the Preview step 2. Verify all information is correct, especially: * Receiver address (double-check this!) * Amount * Delivery deadline 3. Click on the **"Create Escrow"** button
You will need to confirm a blockchain transaction to: * Deposit the payment amount into escrow * Pay gas fees for the blockchain transaction The payment will remain in the escrow contract until: * The sender manually releases payment by clicking "Make a payment" * The receiver manually refunds by clicking their refund option * A dispute is raised and resolved * The escrow expiry date passes and either party executes the transaction Once the payment is submitted and the transaction is mined, you will be redirected to the payment page. {% endtab %} {% tab title="3/ Executing Payment" %} After the service has been provided or trade has been made successfully, this is how you can finalize the transaction. Now, if you click on the escrow contract you just created, you will see a summary of the payment details.
### 3/ Executing Payment #### 3.a. Payment Sender If you are the sender of the payment you'll see the following options when viewing the transaction
**Make Payment**: * Click this button to release funds to the receiver * You can choose to pay the **full amount** or a **partial amount** * Paying a partial amount is useful for settlement scenarios (see Step 4 for more details) * Interface shows: * "Current amount in escrow: \[amount] ETH" * "If you are happy with the service or good provided, you can pay the total amount and complete the escrow. Otherwise, you can make a partial payment. The amount that remains can still be disputed." * Input field: "Amount to pay" (you can enter any amount up to the full escrow balance) * Button: "Send"
**When to pay full amount:** * Service/product was delivered exactly as agreed * You're completely satisfied with the outcome * Click "Send" with the full amount → Transaction closes, receiver gets all funds **When to pay partial amount (Settlement):** * Work was partially completed * Quality issues but some payment is deserved * You want to settle the disagreement without going to dispute * Enter the agreed partial amount → That amount goes to receiver, remainder stays in escrow (can still be disputed if receiver disagrees) **Raise Dispute**: * Click this button if you're not satisfied with the service/product delivery * You'll be shown the arbitration cost (e.g., 0.03 ETH) * You must deposit the arbitration fee to initiate the dispute * Interface shows: * "Arbitration cost: \[amount] ETH" * "By raising a dispute you are petitioning for the full remaining balance." * "You will need to deposit the arbitration cost. This is refunded if you win the dispute." * "The dispute will be evaluated by the Kleros jurors."
#### 3.b. Payment Receiver If you are the receiver of the payment you'll also have two options when viewing the same transaction:
**Reimburse**: * Click this button to return funds to the sender * You can choose to reimburse the **full amount** or a **partial amount** * Partial reimbursement is useful for settlement scenarios (see Step 4 for more details) * Interface shows: * "Current amount in escrow: \[amount] ETH" * "You can fully or partially reimburse the other party. The amount that remains can still be disputed." * Input field: "Amount to reimburse" (you can enter any amount up to the full escrow balance) * Button: "Send"
**When to reimburse full amount:** * You're unable to complete the service/product delivery * You want to cancel the agreement entirely * Click "Send" with the full amount → Transaction closes, sender gets all funds back **When to reimburse partial amount (Settlement):** * You completed some but not all of the work * You want to keep partial payment for work done * You want to settle the disagreement without going to dispute * Enter the amount to refund → That amount goes back to sender, remainder goes to you, transaction closes **Raise Dispute:** * Click this button if the sender refuses to release payment despite you fulfilling the agreed terms * You'll be shown the same arbitration cost (e.g., 0.03 ETH) * You must deposit the arbitration fee to initiate the dispute * The dispute process is identical for both sender and receiver (same interface, same cost, same process) #### 3.c. Understanding Settlements Through Partial Payments Settlement in Kleros Escrow is achieved through the partial payment mechanism described above. There is no separate "settlement mode" - you simply use the partial payment option when both parties agree to a compromise. **How Settlement Works:** **Scenario 1: Sender Initiates Settlement** 1. Sender decides to pay partial amount (e.g., 0.7 ETH out of 1 ETH escrow) 2. Sender clicks "Make a payment", enters 0.7 ETH, clicks "Send" 3. **Result:** 0.7 ETH immediately goes to receiver, 0.3 ETH remains in escrow 4. **Receiver's options:** * Accept the settlement (do nothing, keep the 0.7 ETH) * Reject and dispute the remaining 0.3 ETH * Reimburse some or all of the remaining 0.3 ETH **Scenario 2: Receiver Initiates Settlement** 1. Receiver decides to refund partial amount (e.g., 0.4 ETH out of 1 ETH escrow) 2. Receiver clicks "Reimburse", enters 0.4 ETH, clicks "Send" 3. **Result:** 0.4 ETH immediately goes back to sender, 0.6 ETH remains in escrow **CRITICAL WARNING:** When you make a partial payment or partial reimbursement, **that amount transfers immediately and permanently**. The transferred amount cannot be recovered even if a dispute is later raised over the remaining balance. The dispute will only concern the funds that remain in escrow. **Best Practice for Settlements:** * Document any settlement agreement in writing (email, chat, signed PDF) * Get the other party to confirm they agree to the settlement terms * Save this communication as evidence in case they dispute the remaining amount * If you have written proof they agreed to the settlement, you can use it to win any subsequent dispute {% hint style="info" %} **Note:** Both sender and receiver use the same interface at - the available buttons change based on which wallet address you're using to view the transaction. {% endhint %} {% endtab %} {% tab title="4/ Raise a dispute" %} Whether a partial settlement has been made or not, any of the 2 parties can raise a dispute for the full or remaining payment amount by paying the arbitration fee (that is reimbursed if you win the case). Both parties must pay the arbitration fee. This fee is used to pay coherent jurors in any dispute. ### 4/ Raise a dispute #### 4.a. Raise the Dispute To raise a dispute either party can select the **Raise Dispute** button to pay for the arbitration fees and start the process for arbitration by the Kleros court.
Once a dispute is raised by any party the other party has a limited period of time to pay their side of the arbitration fees after which the Kleros arbitration process starts and can take at least 5-7 days depending on the Kleros court parameters. The UI will update once you have paid the arbitration fee to show the time left for the other party to pay. Below we can see the notifications of payment each party will see.
Once both the parties submit the arbitration fees, they can view the details of the case
{% hint style="warning" %} **INFO** If the other party fails to pay for their side of the fees then the first paying party automatically wins the dispute and can withdraw their funds. {% endhint %} #### 4.b. Share Evidence Once a dispute has been created and both parties have paid their arbitration fees, both parties can submit evidence to support their case. **IMPORTANT:** In Escrow V1, evidence must be submitted through the [Kleros Dispute Resolver](https://resolve.kleros.io/) interface, not through the Escrow frontend. **How to Submit Evidence:** 1. Go to 2. Connect your wallet 3. Find your dispute in the interface 4. Click on your dispute to open the evidence submission page 5. Add your evidence and supporting arguments
**Evidence Best Practices:** * The original Agreement Document details the initial contract * You can add additional evidence such as: * Communication logs with the other party * Proof of delivery or work completed * Photos or screenshots * Any other relevant documentation * **Best practice**: Use PDF files with EXIF data stripped to preserve anonymity * Be clear and concise in explaining why you should win the dispute * Reference specific terms from the original agreement #### 4.c. Monitor the dispute You can monitor the progress of the dispute in two places: 1. **On the escrow payment page** - Shows the current status 2. **On** [**https://resolve.kleros.io/**](https://resolve.kleros.io/) - Shows detailed case information and voting status
**First Ruling:** Once a first ruling has been made by the Kleros Court, anyone who is not satisfied by the ruling can choose to appeal the court ruling: * Appeals request another round of ruling with more jurors than before * Additional evidence can be provided for the jurors to consider * Appeal fees must be paid within the appeal period **Final Ruling:** When the final ruling is made (either after no appeals or after all appeal rounds are complete): * The winning party can withdraw their funds from the escrow * The winning party also receives their arbitration fees back [Learn more about the dispute process.](https://kleros.gitbook.io/docs/products/court) {% endtab %} {% endtabs %} # Kleros Escrow Specifications This page describes the technical flow of the Kleros Escrow smart contracts. It explains how Escrow works behind the scenes for developers and technical users who want to understand the underlying mechanisms. The Escrow V1 system uses two main contracts: * **MultipleArbitrableTransaction** (for ETH transactions) * **MultipleArbitrableTokenTransaction** (for ERC20 token transactions) Both contracts support the appeal functionality through the Kleros Court system. ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-a2a9bcdc18f9d92a067690ca9235c80ac4b96f26%2FStandard%20Escrow%20Flow.png?alt=media) ### **Constructor (deployed by the cooperative)** The constructor of the contract includes: * Address of the arbitrator contract * Extra data for the arbitrator to define court parameters * Time each party has to pay the dispute fee * Multiplier for calculating the appeal fee in the situation when there is no winner and loser in the previous round (e.g. when arbitrator gave "0" ruling) * Multiplier for calculating the appeal fee that must be paid by the winner of the previous round * Multiplier for calculating the appeal fee that must be paid by the party that lost the previous round ### **Create transaction** The flow starts when the transaction is created. The creator of the transaction (sender) deposits the amount that will be held in Escrow and specifies: * **The address that will receive the funds** if the service is successfully provided (receiver) * **Token** - ETH or ERC-20 token to be used for payment {% hint style="info" %} **Token Compatibility Note:** Tokens such as USDT, BNB, and OMG are not supported by Escrow V1. Only standard-compliant ERC-20 tokens are supported. {% endhint %} * **Amount** - The quantity of tokens to be held in escrow * **Delivery deadline** - The date and time by which the service/product should be delivered * **Description** - Details of the service to be provided (text field) * **Agreement PDF** - Optional document detailing the agreement terms #### Timeline Structure 1. **Service Period**: From creation until the delivery deadline 2. **Buffer Period**: Fixed 7-day period after the delivery deadline 3. **Escrow Expiry:** Occurs exactly 7 days after the delivery deadline ### **Pay / Reimburse** The sender can use the `pay()` function to transfer the funds locked in Escrow to the receiver as payment for the provided services. Conversely, the receiver can use the `reimburse()` function to unlock some of the Escrow funds and transfer them back to the sender if the services can't be provided fully. When the escrow expiry date is reached (delivery deadline + 7 days buffer period), the transaction can be executed by anyone calling the contract, which transfers all locked funds to the receiver. This automatic execution only occurs if: * No dispute has been raised by either party * Neither party has manually executed the payment or refund **Note:** All these options are only available if there is no active dispute. ### **Dispute** If the parties can't reach an agreement, they can create a dispute in Kleros Court. To do so, both parties must pay arbitration fees using the functions: * `payArbitrationFeeBySender()` (for the sender) * `payArbitrationFeeByReceiver()` (for the receiver) When one party fully pays its fees, it waits for the other side to do the same. If both parties pay their fees in time, the dispute is created. #### Arbitration Cost The required arbitration cost value can be obtained with: ``` arbitrationCost(_extraData) ``` where `arbitrationCost()` is a function of the arbitrator contract. This function returns the amount in wei and requires the extra data (the same that was used in the constructor) to be passed as an argument. #### Fee Timeout If a party doesn't pay arbitration fees in time, it can be timed out using either `timeOutBySender()` or `timeOutByReceiver()`, depending on which party didn't pay. In this case, the party that fully paid the fees wins and gets all the locked funds. Both parties have their arbitration fees fully reimbursed in this scenario. #### Dispute Outcomes When the dispute is created, it can be resolved with three possible outcomes: 1. **Sender wins**: Gets all the locked funds and arbitration fees reimbursed 2. **Receiver wins**: Gets all the locked funds and arbitration fees reimbursed 3. **Tie/No clear winner**: The court didn't favor either party. Reimbursed fees and locked funds are split equally between the parties #### Evidence Submission Until the dispute is resolved, parties can submit evidence to support their claims. **Note:** In Escrow V1, evidence must be submitted through the [Kleros Dispute Resolver](https://resolve.kleros.io/) interface, not through the Escrow frontend. Parties should navigate to their dispute in the Dispute Resolver to add supporting documentation and arguments. ### **Appeal** The dispute ruling can be appealed by depositing the appeal fee within the dispute's appeal period. If appeal funding is successful the dispute will be arbitrated again with more jurors. #### Appeal Fee Calculation The required appeal fee value is computed by the formula: ``` appealCost(_disputeID, _extraData) × (10000 + multiplier) / 10000 ``` Where: * `appealCost()` is a function of the arbitrator contract that returns the appeal cost * `_disputeID` is the ID of the dispute given by the arbitrator when the dispute is created * `_extraData` is the same extra data value used in the Constructor * `multiplier` is the stake multiplier defined by the outcome of the previous round: * **sharedStakeMultiplier**: if the dispute didn't have a winner and loser in the previous round (e.g., when arbitrator gave "0" ruling) * **winnerStakeMultiplier**: if the appealing party won the previous round * **loserStakeMultiplier**: if the appealing party lost the previous round These multipliers are set when the contract is deployed. #### Appeal Process **Important:** In Escrow V1, only one party needs to pay the full appeal cost to trigger a new arbitration round. For example, if the sender loses the initial ruling, the sender can click the appeal button in the UI during the appeal period, pay the appeal fee, and the dispute will enter a new round of arbitration. The other party does not need to pay for the appeal to proceed. Each party pays their own appeal fees directly. The appeal process is managed through the Kleros Court system. If the dispute is not appealed within the appeal period, it receives the final ruling from the arbitrator and the transaction is marked as resolved. The ruling can then be executed and funds are distributed accordingly. # Retired # Tokens A community-curated list of fungible Tokens 🟣 [Kleros Tokens Registry](https://curate.kleros.io/tcr/100/0xeE1502e29795Ef6C2D60F8D7120596abE3baD990) 🟣 **Kleros Tokens** is an open and decentralized curated registry of tokens. In other words, it is a community-managed list of ERC-20 tokens (including their name, ticker, logo and address) open to any project and curated by the power of Kleros arbitration and economic incentives.
## Why does the ecosystem need a decentralized and open list of tokens? As the Ethereum ecosystem continues to evolve, the rate at which new ERC-20 tokens are being created is expected to accelerate. With this, it becomes increasingly difficult for users to filter out high quality, legitimate tokens from scams, fakes, and duplicates. Many projects have taken to managing and maintaining their own token lists and the end result is a lot of duplicated work and drawn out listing processes which fail to keep pace with the developments in the market. In addition, builders should be able to focus on building, not deciding which tokens are legitimate. **Kleros Tokens** is a solution to this problem: a community-managed initiative to improve discoverability and trust in ERC20 tokens in a manner that is inclusive, transparent, and decentralized. ## Decentralizing the listing and curation process for tokens In the legacy financial system, gatekeepers manage the lists of assets on a discretionary basis. Without listing, the utility of an asset is severely diminished. Unlisted assets often can’t be transferred, traded or used in any other capacity. In the Ethereum-based decentralized financial system, the concept of “listing” takes on a new meaning. Anyone can create a new ERC-20 token and transfer it to anyone else, and it will be publicly recorded on the Ethereum blockchain. Since most fungible tokens nowadays use a standard interface (e.g. ERC-20), infrastructure-layer applications, such as wallets, analytics sites, and DeFi protocols (like Uniswap) can immediately recognize and interact with new ERC20 tokens from the moment they are deployed. As the decentralized finance movement continues to remove gatekeepers, it is imperative that new systems for discovery and reputation do not devolve into centralized gatekeeping, which is why Kleros Tokens registry is designed to be completely open and transparent. ## How does it work? Anyone can submit a token and its information with a deposit. The submission goes through a challenge period. * If no one challenges it, it is automatically accepted into the list. * If someone challenges it by putting up a deposit, then it goes to Kleros Court for arbitration. It is also possible to make a removal request for an entry already accepted into the registry. The full instructions for how to submit to the registry can be found [here](https://blog.kleros.io/how-to-submitting-to-the-security-metadata-registries-on-kleros-curate/). ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-c7167384c4d34b98b277aee494790285c7e58c6b%2FCurate_Infographic_Header_cropped.png?alt=media) ## What type of information is stored in the Tokens registry ### Tokens The Tokens registry contract contains all token submissions. A token submission contains the token's data its current status and request history. * Name - The token's name (e.g. Gnosis). * Ticker - The token's ticker (e.g. GNO). * Address - The token's address * Decimals - The number of decimals that the token can denote * Logo - The token logo image ## Use cases Kleros Tokens is already one of the most popular [Token Lists](https://tokenlists.org) (and the only decentralized one) and is thus used by the likes of Uniswap, Sushiswap, Zerion, Swapr etc... as a way to list tokens in their application. # Linguo A Decentralized Translation Platform 🤖[Linguo App](https://linguo.kleros.io) 🤖\ \ **Linguo** is an easy-to-use decentralized translation Dapp allowing both translators and translation requesters to interact in a completely trustless manner. It came to light due to our own internal needs for multi-language translation of Kleros content. As it turns out, you can get quality services at a low price when calling on the decentralized free market.You can use this tutorial from [Binance Academy](https://academy.binance.com/en/articles/how-to-use-metamask) to help you do this.
# Kleros Linguo Tutorial How to use Linguo to translate content or request a translation Linguo is so straightforward, it doesn't really need an explainer but we're going to make one anyway... and then have it translated on Linguo into various languages ofc. Let's get started. ## Translate Your Content Enter [linguo.kleros.io](https://linguo.kleros.io/) and you'll be greeted with the following screen (you may be notified to connect your Web3 wallet). Here, you can select whether you want to translate something, have something translated, or review anything that falls into the former two categories. Our aim is to have content translated so we'll click on 'My Translations'. ![Linguo Dashboard](https://blog.kleros.io/content/images/2020/11/Linguo-Welcome.png) You'll be taken to the following screen in which you can fill in all the details in relation to your content including: source language, target language, expected quality and price. ![Request a translation](https://blog.kleros.io/content/images/2020/11/Request_Translation.png) > **Note:** More languages will be added in the future. There are currently three varying quality tiers available: * **Cost Effective.** The conveyed meaning must be similar, but nuances might be lost. Occasional typos and translation errors are acceptable. Translators having a self-declared level B2 (CEFR) or higher will be able to see this task. * **Standard.** The meaning must be almost identical. Occasional typos are acceptable. Only translators having a self-declared level C1 (CEFR) or higher will be able to see this task. * **Professional.** The meaning and spirit of the translation must remain identical and the translator must reflect the style and nuances of the original text. Translators are expected to have their text reviewed before submission. Only translators having a self-declared level C2 (CEFR) will be able to see this task. We recommend using the 'Professional' quality for white papers, websites and other technical documentation. ![Set your source and target languages](https://blog.kleros.io/content/images/2020/11/Request_2.png) Give your translation an appropriate and relevant title, upload a PDF, JSON, text or other various document file type and add the amount of words required for translation.Pricing ![Set the parameters and load the content files or links for your translation.](https://blog.kleros.io/content/images/2020/11/Upload_Price_Details.png) The pricing section is where it gets more interesting. Here, you will see three parameters: Deadline, MinPrice and MaxPrice. The price rises linearly from the start date to the finish date offering an auction-like scenario for translators to decide their own personal acceptable price point for each piece of content. For example, you can price your translation to be picked up quickly by opening with a high minimum price. Conversely, a broad spread between the minimum and maximum price set over a longer deadline (30 days, for example) gives a steadier price increase over time starting from a more reasonable entry point. If you just want a fixed price translation with no price discovery, set both the Min and Max price to the same value.The pricing system. High initial prices will likely get your translation completed quicker. ![Once you've set your desired price and deadline above, click 'Request the Translation'.](https://blog.kleros.io/content/images/2020/11/Price-explainer.png) You will now pay the maximum price set for the translation and the gas fee to the Linguo contract. This functions as a temporary one-way escrow of sorts and you will be refunded any outstanding balance from the maximum price as soon as a translator takes the job. This ensures the deadline to price ratio can be fulfilled. In our example above, 1.5 ETH was transferred to the contract and 1.23 ETH returned after the translation was taken two days after listing at a cost of 0.27ETH. ## The Dashboard Clicking back on 'My Translations' brings you to the dashboard where you can see our recently posted job amongst others with a brief overview of the job along with current pricing and deadline info.The 'In Progress' tab shows much the same info except, the price stated here is final. ![](https://blog.kleros.io/content/images/2020/11/Dashboard.png) For example, the second posting in the image below shows an English to Chinese translation of our juror starter kit accepted at the total price of 0.31 ETH ($144) or 0.26 mETH (0.12c) per word. ![In progress jobs tab with finalized translation prices.](https://blog.kleros.io/content/images/2020/11/Dashboard_Inprogress.png) ## Work as a Translator For those looking to work as translators, the setup is just as simple. Click on 'Work as a Translator' and you'll see a screen much like the one below. Here, you can see any of the open jobs which match your language skills. At this point, we haven't added any language skills so let's do that now. Click on 'Update Skills'. ![On first selection, the tasks modal will be empty.](https://blog.kleros.io/content/images/2020/11/Work_empty.png) Once you're in the 'Set Language Skills' page, you'll be presented with a number of drop-down menus in which you select the language you want to work in and the translation level you have for that skill. > **Note:** Only add language skill levels you are confident with otherwise, your translations will likely be challenged and you may not get paid! Now that we've set some languages, you can see a number of postings have appeared. For two of those, we have the required skillset and one (greyed out) is not within our skillset and therefore, not able to bid on. If you have just arrived on Linguo for the first time, you'll be directed to the 'Update Skills' section above by default. ![Open jobs dashboard](https://blog.kleros.io/content/images/2020/11/Work_Open_tasks.png) ![Set the languages you are skilled in and the level.](https://blog.kleros.io/content/images/2020/11/Translator_Selection_Language.png) By clicking on 'See details' you can preview each translation including cost and the content to be translated. ![Task details](https://blog.kleros.io/content/images/2020/11/Apply_Work.png) If you're happy with everything, click 'Translate It'. Take note, you must make a deposit at this point to confirm you will complete the translation in the given deadline. If not, you will lose this deposit and it will be paid to the original requester as compensation. Once the translation is completed satisfactorily and there are no disputes, you will receive this deposit back along with the originally set payment for the work. ## Dispute resolution - Enter Kleros Court In the event that a translation requester is not happy, they have the option to dispute the work which in turn, sends it to Kleros jurors for evaluation. Each case will be sent to the corresponding court as defined by the target translation language. Jurors are incentivized to stake only in courts they have sufficient linguistic knowledge. ![Review completed translations.](https://blog.kleros.io/content/images/2020/11/Review-list.png) Once a translation has been completed it will be visible in the 'Review List' tab. There is a 7 day review period in which the job can be challenged if the quality of the content is not up to the desired standard. Click 'See details to move to the next screen'. ![Review](https://blog.kleros.io/content/images/2020/11/Translation-Delivered.png) Here, you can view both the original and translated text along with the option to raise a dispute by paying the deposit and adding any evidence you have substantiating the claim. ![](https://blog.kleros.io/content/images/2020/11/Screen-Shot-2020-11-19-at-9.28.42-PM.png) Jurors staked in the corresponding [court](https://kleros.io/) to the target language will be drawn to resolve any translation issues. > Note: In the first round of Linguo disputes, only 1 juror will be drawn. Jurors are nonetheless incentivized to carefully judge cases, as their incentives can depend on how larger panels of jurors rule in any future appeals. ### To Conclude Linguo can be used for all manner of content including white papers, websites, articles, video transcription, and much more. Using the linear pricing method coupled with a set deadline offers both sides of the deal a mechanism to get fair pricing, high quality, and quick turnaround. # Step-by-step Tutorial This is a step-by-step guide that explains how to use Linguo. Please go through it to acquaint yourself with the platform! Before you begin you need to, * [ ] Set up a decentralised wallet. {% hint style="info" %} You can use this tutorial from [Binance Academy](https://academy.binance.com/en/articles/how-to-use-metamask) to help you do this. {% endhint %} * [ ] Connect to the Gnosis (xDai) chain. {% hint style="info" %} Here is a helpful tutorial from [Gnosis](https://developers.gnosischain.com/for-users/wallets/metamask/metamask-setup) to help. {% endhint %} * [ ] Fund the wallet {% hint style="info" %} If you don't have Ethereum get some! [Here's how.](https://ethereum.org/en/get-eth/) If you already have Ethereum you can follow the [tutorial](https://jaredstauffer.medium.com/how-to-get-xdai-how-to-convert-dai-to-xdai-eth-dai-xdai-30a60e4b6641) here. {% endhint %} Now you can head over to the [Linguo page and get started. ](https://linguo.kleros.io/home) Linguo currently runs the Gnosis (xDai) chain since gas fees are lower, so make sure you’ve connected to the Gnosis (xDai) chain before continuing with the rest of the tutorial. Once you have everything set up, navigate to the home page and connect your wallet. You now have 3 options; * [Request a translation.](/products/retired/linguo/step-by-step-tutorial/requesting-translations) * [Work as a translator](/products/retired/linguo/step-by-step-tutorial/working-as-a-translator). * [Review submitted translations.](/products/retired/linguo/step-by-step-tutorial/reviewing-translations) # Requesting translations 1\. Click on the My Translations option to see a list of ongoing translation requests that you have submitted.

Alternatively, you can click the request translations above to reach the same page.

2\. Click the new translation button to begin the submission.

Click on New Translation

3\. Fill out the form and click next to continue with the next step. {% hint style="success" %} * Choose your source language (the language you want to translate) and your target language (the language you are translating to). * Choose the expected quality of the translation (make sure you choose carefully as this helps translators choose appropriate tasks. {% endhint %}

Fill out the form depending on your requirement.

4\. Now input all the details of your request and click Request the translation. {% hint style="success" %} Ensure this form is filled out accurately to avoid disputes. {% endhint %} {% hint style="success" %} **The pricing section is where it gets more interesting. Here, you will see three parameters: Deadline, MinPrice and MaxPrice.** The price rises linearly from the start date to the finish date offering an auction-like scenario for translators to decide their own personal acceptable price point for each piece of content. For example, you can price your translation to be picked up quickly by opening with a high minimum price. Conversely, a broad spread between the minimum and maximum price set over a longer deadline (30 days, for example) gives a steadier price increase over time starting from a more reasonable entry point. If you just want a fixed price translation with no price discovery, set both the Min and Max price to the same value. The pricing system. High initial prices will likely get your translation completed quicker. {% endhint %}

Almost done.

5\. You will now be prompted with a transaction in your wallet. Please double-check the details and click confirm.

This will create a new task as per your specifications.

6\. Your request is now active! A translator should pick it up shortly.

Your request will appear on the list!

{% hint style="info" %} **In case your request isn’t picked up on time, you can collect your deposit by clicking ‘Reimburse Me’.** ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2FdpyszMpkV03rafmtExsj%2Fimage.png?alt=media\&token=090830fa-3a48-4301-b1da-fb202a2772d1) {% endhint %} 7\. You will be notified every time an update happens on your request. You can see them by clicking the notifications icon on the upper right-hand side.

You can see updates every step of the way.

8\. Once the translator submits the translation, it will be under review for 7 days. During this time you or any jurors can review it and create a dispute if the final result isn’t satisfactory or doesn’t meet your specified requirements! {% hint style="info" %} If you want to dispute the translation you can do it as follows. * To submit a challenge navigate to the request page, gather your evidence in a file and upload it by clicking the Evidence for Challenge button and confirm the transaction in your wallet. ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2F3FQf31cHgLeCK970lONK%2Fimage.png?alt=media\&token=c8670893-c552-49c4-b176-2b57c6be4cc0) * Once you’ve submitted the evidence and made the challenger deposit the case will be sent to the respective courts to be evaluated by the jurors. ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2FNXI9oOeOH9i3QRFRkZpZ%2Fimage.png?alt=media\&token=0e76f679-dfb2-4b85-a09f-151cad2d4d03) {% endhint %} # Working as a translator 1. Click on Work as a translator to get started.

The link on the header takes you to the same place!

2\. Since this is your first time translating on Linguo you need to create a profile and do a self-assessment before you can start. Please make sure you do the self-assessment accurately as this would ensure you get matched to jobs that you are most suited for.

Enter all languages you are comfortable with and hit save.

3\. You will now see all open translations, see if you are qualified to work on them, and the total price offered for completing the task.

Choose an open task that you are qualified for and comfortable with.

4\. Once you choose an open task you can review the original document by clicking the button.

Skim through the document to ensure that you can meet the requirements.

5\. Now you can accept the request by clicking the ‘Translate It’ button and depositing the mentioned amount. Ensure that you have the mentioned amount of xDai in your wallet.This deposit will be refunded along with the payout after a 7-day review period once you have submitted the translation. In case there is a dispute and the challenger wins, you will lose the deposit.

Hit translate!

6\. Now confirm the transaction in your wallet to make the deposit and accept the Task.

You have now accepted the task as soon as the transaction goes through!

7\. Now you can download the document and start working on translating it! {% hint style="info" %} To find tasks you’ve accepted on the sort tab and filter by ‘In Progress’ or ‘All Status’ ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fr6xXl23TQHfqTU6KBKQt%2Fimage.png?alt=media\&token=8c7ce9b8-44bf-4a03-8f64-bdf1cfb5f53e) {% endhint %} 8\. Once you are done with the task you can upload the file by hitting the Translated Text button.

Make sure you're uploading the right file!

9\. Click the Submit Translation button and confirm the transaction in your wallet.

This will submit your translation.

10\. You’re all done, once the review period ends you can collect the payment as well as your deposit!

Congrats! You've submitted your first translation.

{% hint style="info" %} **What happens if your translation is challenged?** If your translation is challenged there will be a dispute created that will be resolved by the Kleros court. If the challenger wins, you will lose your deposit. If the challenge is rejected, you will receive; payout = your bounty + (challenger fees - arbitration fees) + your deposit. {% endhint %} # Reviewing translations You can also earn by reviewing translations done on the platform. Here is how that works! 1. Click the Review Translations option to see available translations to be reviewed.
2\. Create a profile and fill in your language proficiency details. {% hint style="info" %} Please make sure you do the self-assessment accurately as this would ensure you get matched to jobs that you are most suited for. {% endhint %}

Enter all languages you are comfortable with and hit save.

3\. Now you will see all open translations for review.

Select a file that matches your skillset.

4\. Once you have chosen the file you’d like to review, gather your evidence and challenge the submission.
5\. Once you’ve submitted the evidence and made the challenger deposit the case will be sent to the respective courts to be evaluated by the jurors. {% hint style="info" %} **What happens now?** If your challenge is rejected you lose the challenger deposit. If your challenge is approved; your payout = translator deposit + (challenger deposit - arbitration fees) {% endhint %} # F.A.Q Here you can find answers to frequently asked questions.
How does Linguo evaluate the translator's skills? Short answer: Linguo is permissionless, so it does not. Translator skills are self-declared.
If there is no evaluation process, how can I be sure the translator is qualified enough for the job? Linguo uses crypto-economic incentives to regulate the behaviour of users. Translators are required to provide a deposit when they are assigned to a task. After the translated text is submitted, there is a review period. During this time, anyone (including yourself) can look for potential flaws in the translation and raise a challenge. If a translation is challenged, a case is created in a specialized Kleros court which decides whether or not the translation fulfils the requirements. If the challenger wins the case, the translator loses the initial deposit, which is then sent to the challenger as a reward for her or his work. This way we incentivize translators to only accept tasks they think they are qualified enough to work on, otherwise they will suffer financial losses.
How are translator skills defined in Linguo? Linguo considers language skills as defined by the [Common European Framework of Reference (CEFR).](https://www.coe.int/en/web/common-european-framework-reference-languages/level-descriptions)
I am not sure how I rank on the CEFR scale. How can I find out? You can test your skills by using this [self-assessment grid.](https://rm.coe.int/CoERMPublicCommonSearchServices/DisplayDCTMContent?documentId=090000168045bb52)
What are the Linguo translation tiers? Linguo translation tasks can be defined in 3 different quality tiers: Cost Effective: A basic translation. The conveyed meaning must be similar, but nuances might be lost. Occasional typos and translation errors are acceptable. Standard: The standard level of a translation. The meaning must be almost identical. Occasional typos are acceptable. Professional: Professional translation. The meaning and spirit of the translation must remain identical and the translator must reflect the style and nuances of the original text. Translators are expected to have their text reviewed before submission.
How do my skill levels affect the number of tasks I will be able to work on as a translator? Translation tasks are available according to the required translation tier as specified by requesters: Cost Effective: translators with B2 level and above.Standard: translators with C1 level and above.Professional: only translators with C2 level. Notice that if your level is lower than B2, you will not be eligible for any translation tasks in Linguo.
Why does Linguo support only translations to and from English?
I need a translation between two languages other than English. What do I do then? Currently, finding specialized jurors to evaluate a translation between an arbitrary pair of languages has been challenging (e.g.: Korean ↔ Russian). We use English as the “pivot” language, so there can be enough jurors. At this point, there is one way to do this. Let’s say you want a translation Korean → Russian: 1. You should first create a translation task for Korean → English. 2. Then, after this intermediate translation is delivered, you can create another one for English → Russian.
Why do I need to set a minimum and a maximum price when requesting a translation? From the moment you create the translation task to the moment some translator assigns it, the price will increase linearly. The higher the payout, the more interesting it will be for translators to work on your translation task. This will help you discover the right prices for your tasks. If you would like to avoid this mechanism, you can set the same value for both minimum and maximum prices.
What happens to my deposit if a translator picks up the task before it reaches the maximum price? From the moment you create the translation task to the moment some translator assigns to it, the price will increase linearly. The higher the payout, the more interesting it will be for translators to work on your translation task. This will help you discover the right prices for your tasks. If you would like to avoid this mechanism, you can set the same value for both minimum and maximum price. When a translator is assigned to a task, your remaining deposit — the maximum price minus the current price — is immediately sent back to your wallet. This is done automatically, there is no need for user input.
Is there a limit on the number of translation tasks I can request on Linguo? No. You can request as many tasks as you want, even at the same time.
Is there a limit on the size (text length) of translation tasks I can request on Linguo? There is no hard limit. If a task is too long, reviewers will probably try to optimize their work and evaluate only certain segments of the whole text. This might lead to reviewers overlooking certain mistakes in the translation. It is safe to expect that reviewers will be efficient enough in finding errors (as they are financially incentivized to), however, if the translation is critical, you should also make sure to do a double check and review the translation yourself. We advise you to break longer translations into multiple parts whose individual size is around 4,000 words. Notice that currently there is no guarantee that all individual tasks will be assigned to the same translator, as anyone with the required skills could do this at any time.
Should I trust the word count for a given translation task displayed on the Linguo interface? The short answer is: no! Always double-check it yourself. Linguo works with several languages and a myriad of file formats. There is currently no fail-proof way to determine the word count for a translation task. While we do have some heuristics in place to get the approximate word count for text-based file formats, such as TXT, PDF or JSON, its input is ultimately controlled by the translation requester.
What are the different fees? Challenger Fee: Deposit paid by a challenger when raising a dispute. Translator Fee: Deposit paid by translator while accepting a translation request. Arbitration Fee: Paid out to jurors for ruling on a dispute.
# High-level Overview Here is a flow chart that gives you an overview of how Linguo works.

Follow the legend.

# Moderate Social media content moderation with Reality.eth x Kleros **Kleros Moderate** is a family of content moderation bots which use Reality.Eth with Kleros as an [Oracle](/products/oracle) for moderation decisions (did the user break the rules?).

Community management is hard, Kleros Moderate can help

Supports * Telegram : ⚖️ [Susie | Kleros Moderator](https://t.me/SusieTheKlerosModeratorBot?start) ⚖️ * Discord : - How does it work?

Crowd-sourcing moderation with Reality.eth & Kleros

# Susie A moderation and group management bot for Telegram

Susie | Kleros Moderator

## Guide ⚖️ [Susie | The Kleros Moderator](https://t.me/SusieTheKlerosModeratorBot?start) ⚖️\ \ Welcome to the guide for using Susie the Kleros Moderator! The menu on the left lists the available features. To learn more, join the [@SusieSupport](https://t.me/SusieSupport) Telegram group. # Getting Started Add Susie to your group and get started. ## Susie Setup Setting up ⚖️ [Susie | The Kleros Moderator](https://t.me/SusieTheKlerosModeratorBot?start) ️⚖️ in your telegram group isn't difficult, however, to save yourself any trouble later on, we highly recommend that you read the docs and get familiar with Susie's features. The docs are written to help you get Susie running as quickly and easily as possible. Feel free to bookmark this guide as a quick reference. For further questions, please visit our Telegram group [@SusieSupport](https://t.me/SusieSupport) which has experienced users who are familiar with Susie and her features who will be happy to assist you. Thanks! # Add Susie Adding Susie to your Telegram group is easy! ## Add Susie to your group [⚖️ Susie | The Kleros Moderator ⚖️](https://t.me/SusieTheKlerosModeratorBot?start) will prompt you to add her directly to your telegram group. The link should open your Telegram client to select the chat you wish to add Susie to. Please add Susie as an admin. Alternatively, follow the manual steps below 1. Open Telegram 2. Search for the user [@SusieTheKlerosModeratorBot](https://t.me/SusieTheKlerosModeratorBot?start) ***(\*)*** 3. View Susie's profile, and click the 3-button menu in the top right corner and select the “Add to group” option, then choose your group. 4. Congratulations! You've added Susie to your group ***(\*)*** You may see other bots or users with similar names or usernames. Make sure you only add the bot with the username [@SusieTheKlerosModeratorBot](https://t.me/SusieTheKlerosModeratorBot?start), others are imposters! # Start Susie Susie will help you walk through the start process with /start ## /start If you added Susie as an admin to your group by following a [link](https://t.me/SusieTheKlerosModeratorBot?start=botstart), then she automatically starts and you can skip the rest of the following steps. If you manually added Susie to your group, there is one more step to unlock her full potential. Remember, Susie can't help moderate your group until she is an Admin! Without admin rights, she won't be very useful. Thankfully, promoting Susie to an Admin role is simple, 1. Select the banner at the top of your group to view your group's information 2. Select the pencil icon to edit your group's settings 3. Select “Administrators”, and then “Add Administrator” 4. Select Susie from the list of users 5. Grant her all admin rights as shown, and click the checkmark icon Finally make sure to use the /start comand to begin Susie's community moderation. Congratulations, you've now unlocked Susie's full potential! ### Admin Command /start: Begins Susie's community moderation # Basics Susie can help you do some really cool and powerful crowd-sourced moderation in your group chats. That being said, in order to properly configure her and have the smoothest experience possible, there are some basic commands that you should familiarize yourself with. The guides in this section will show you how to properly use these commands. # Welcome Susie's ability to welcome users to your group chat not only is polite, but it is an easy way to inform new members about the rules. ## Enabling Welcomes To get started, you'll want to actually enable your welcomes. It's that easy. ## Captcha Susie can use her greeting to help fight spam bots that may attempt to join your group chat. This setting mutes all new users until they engage a button to confirm they read the rules to unmute themselves. This can help prove they're not a bot! ### Admin Command `/welcome`: toggles welcome message `/captcha`: toggles captcha ### Ad # Language Susie speaks English and Spanish. | Language Code | Language | | ------------- | -------- | | es | English | | en | Español | Join the [@Susie Support](https://t.me/SusieSupport) Telegram group to request Susie to study a new language. ### Admin Command `/lang :` Sets language # Notifications 🔔🔔🔔 Susie sends notifications about moderation actions and report updates. These notifications can be sent to a notification channel to avoid cluttering the group. ## Enable Notification Channels: 1. Make a channel 2. Add Susie 3. Susie will send a channel ID 4. Use that channel ID to set notifications with /setchannel in the original group ### User Command `/notifications`: Returns current notification channel ### Admin Command `/setchannel` : Sets the notification channel `/setchannelfed` : Sets the federation notification channel # Rules Users can request Susie to send them the rules anytime, making group admin easier. ### Viewing Rules Any user in your group chat can request to view your group chat's rules. ### User Command `/getrules` ## Setting Up Your Rules Every groups starts with [default rules](https://cdn.kleros.link/ipfs/Qme3Qbj9rKUNHUe9vj9rqCLnTVUCWKy2YfveQF8HiuWQSu/Kleros%20Moderate%20Community%20Rules.pdf). You can also set customize the rules. **Rule Writing Tips** * State the group culture in a preamble. * Number each rule. * Be specific. ### Admin Command `/setrules `: Sets rules to the replied message. `/setrules `Sets rules to the specified URL. # Reports Who Moderates the moderators? As groups grow, so do their moderation problems. We're all busy people who don't have time to monitor groups 24/7. Moderators are asleep, and some jerk comes in and starts spamming all over the place? Moderators broke the rules? Who Moderates the moderators? Often users dispute moderation actions by admins and have no recourse. Susie enables crowd-sourced moderation using [Reality.eth and Kleros](/products/oracle). When users are reported, a question is created on Reality.Eth asking 'did the user break the rules?'. The question can be answered yes/no with a bond (1 DAI). Successful reports result in penalties (1 day, 10 days, 100 days, permaban).
Answers to reports can be disputed, creating a case in the [Kleros Court](/products/court). ### User Commands `/report` Reply to a message to report it `/info` Returns active reports in a group `/info` \ Returns report history for user ### Admin Commands `/adminreportable` Allows admins to be reported. `/trial` Toggles a trial version of Susie where no penalties are enforced. # Evidence Evidence 🔍🔍🔍 Susie can help collect evidence of misbehavior and save it from tampering. ### User commands `/evidence` : Reply to a message to add it as evidence # Federations Moderating a single group is hard, but managing multiple is even harder
Do you have to ban spammers manually, in all your groups? No more! With federations, Susie can enforce a ban on a user in all federate groups. Note that currently only the creator of the federation has the ability to add new groups to a federation. Other users can "follow" a federation, meaning bans in the federation are applied locally, but local bans do not result in federation bans. ### User commands `/fedinfo` Returns current federation ### Admin commands `/newfed` Creates a federation `/joinfed` Joins the current group to a Federation # Overview How to integrate with Kleros? ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-c2b4c8d74037f9f14f6078816b553797a00e9336%2FSECURED_BY_KLEROS_GREY%20\(2\).png?alt=media) ### Why do you want to integrate with Kleros services? * If you are looking for pure **Arbitration-as-a-Service**, we can help you integrate with our core service [Kleros Court](https://kleros.gitbook.io/docs/products/court). * If you want an oracle that can provide rulings about events, connect to [Kleros Oracle](https://kleros.gitbook.io/docs/products/oracle) and get **Truth-as-a-Service** capabilities. * If you are searching for **Data-Curation-as-a-Service**, use our [Kleros Curate](https://kleros.gitbook.io/docs/products/curate) generalized TCR product to build open community-curated lists and read from them. * If you want to manage crypto-vs-crypto transactions or service-vs-crypto transactions in your app, have a look at [Kleros Escrow](https://kleros.gitbook.io/docs/products/escrow) contract (+ Widget & SDK) for **Escrow-as-a-Service** features. * If you are a DAO looking to fully decentralize your governance (even the enforcement of proposal votes), check out [Kleros Governor](https://kleros.gitbook.io/docs/products/governor) and use it as **Supreme-Court-as-a-Service**. ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-d3342c093bab24c6a18e2e71c41a83f51dd3cb74%2Fimage.png?alt=media) ### What about Kleros products built on top of those services? * Your DeFi application can source its token data directly from[ Kleros Tokens](https://kleros.gitbook.io/docs/products/tokens) registry and even curate the tokens using badges (e.g. filtering them using preset criteria) or indirectly through [TokenLists.org](https://tokenlists.org/token-list?url=t2crtokens.eth) * Your product can use Sybil-resistance properties of [Proof of Humanity](https://kleros.gitbook.io/docs/products/proof-of-humanity) to protect against Sybil attacks or identify your users. * You can apply to or benefit from decentralized translation jobs in [Linguo](https://kleros.gitbook.io/docs/products/linguo) to handle the internationalization of your products. {% content-ref url="/pages/-MTewstJdyJJK\_Kn0Jca" %} [Types of Integrations](/integrations/types-of-integrations) {% endcontent-ref %} {% content-ref url="/pages/-MSY1Ji1VU\_FQv8E31qI" %} [Integrations FAQ](/integrations/integrations-faq) {% endcontent-ref %} {% content-ref url="/pages/-MQqjOgHc9UhwJ4CDp9T" %} [Use Cases](/integrations/types-of-integrations/1.-dispute-resolution-integration-plan/use-cases) {% endcontent-ref %} {% content-ref url="/pages/-MR5YS1eoIeBVjP9GQF5" %} [Integration Tools](/integrations/types-of-integrations/1.-dispute-resolution-integration-plan/integration-tools) {% endcontent-ref %} {% content-ref url="/pages/-MXgYsxGh4ldxDVmkh6B" %} [Live & Upcoming Integrations](/integrations/live-and-upcoming-integrations) {% endcontent-ref %} {% content-ref url="/pages/-MRQDv347QIv5xQernH4" %} [Scalability & Cross-chain](/integrations/scalability-and-crosschain) {% endcontent-ref %} {% content-ref url="/pages/-MRL30KQRi7iuE9-VQKM" %} [Kleros Analytics](/integrations/analytics) {% endcontent-ref %} # Industry use cases Check out [kleros.io/industries](https://kleros.io/industries) for a collection of guides made specifically for your industry! # Types of Integrations Have a look at the paths to integration While there are [numerous ways](/integrations/live-and-upcoming-integrations) to make use of Kleros, but they can be broadly put into two categories: 1. [Using Kleros to **resolve disputes**](/integrations/types-of-integrations/1.-dispute-resolution-integration-plan) 2. [Reading and using **curated data** from public on-chain registries secured by Kleros Court](/integrations/types-of-integrations/2.-curated-data-integration-plan) 3. [Using Kleros **oracle services** to obtain verified real-world information for your DApp](/integrations/types-of-integrations/3.-kleros-oracle-integration) Click on one of the links above to dive into their respective integration plans! # 1. Dispute resolution integration plan Solution plan for integrating Kleros as an arbitrator to decide on disputes ## Introduction Using [**Kleros Court**](/products/court) to decide on disputes is the most direct way to use Kleros. The ways to use this are numerous, but here are a few of them: * **Escrow** (see [Kleros Escrow](/products/escrow)) * **(DeFi) insurance claim disputes** (see our partnership with [Unslashed Finance](https://blog.kleros.io/welcome-to-decentralized-insurance-kleros-x-unslashed-finance/)) * **Bounty and job payment disputes** (see the integration with [Feature.sh](https://docs.feature.sh/guides/challenge-a-claim)) * **Securing oracle result resolutions** (see the [documentation](https://kleros.gitbook.io/docs/integrations/types-of-integrations/how-to-use-reality.eth-+-kleros-as-an-oracle) and the [Kleros+Gnosis’s partnership](https://blog.kleros.io/kleros-x-safesnap/)) * **Real-world arbitration** (see this example [from Mexico](https://blog.kleros.io/how-to-enforce-blockchain-dispute-resolution-in-court-the-kleros-case-in-mexico/)) A full list of Kleros's existing integrations and partnerships can be found [here](/integrations/live-and-upcoming-integrations). Integrating Kleros into your dispute decision process will always involve 5 main steps and they are outlined below. {% hint style="info" %} To help you keep track of your integration process, click [**here**](https://docs.google.com/document/d/11HUXGV25cy_DMKXJvIn7LeAGBjY7ohXtO5uNN_C9wI0/copy?copyComments=true) to make a copy of our Dispute Resolution model integration plan! {% endhint %} To help you keep track of the process, click here to make a copy of our model integration plan! ## Key integration steps Following these 5 steps in sequence will ensure that your integration is secure and runs smoothly for both you and your users. ### 1. Determine the conditions for escalation and enforcement An integration with Kleros implies that you have chosen for the jurisdiction of Kleros Court for the resolution of a dispute. As with real-world courts, Kleros Court is only an arbitration service, and it is important to remember that our decentralized jury only takes care of the ruling on a dispute given certain facts/evidences and policy documents. Enforcement of the ruling is out of scope for Kleros, and needs to be carefully taken care of by your service/platform/dApp. What this means in concrete terms is that you need to decide on and document the following before escalating a dispute to Kleros: * **Escalation criteria**: when your platform will allow an escalation of a dispute to Kleros * Example: *escalation is only allowed after a first round of dispute resolution has taken place within your platform, and the disputed transaction above a certain transaction value.* * **Enforcement criteria**: what criteria need to be fulfilled for your platform/service to commit to enforcing a ruling from Kleros * Example: *enforcement is dependent on the agreement of DAO governance or approval committees, if the enforcement is governed by a 'multisig', of which Kleros Court represents only 1-of-n signers.* {% hint style="info" %} If a smart contract integration with Kleros Court is used (see [**Step 4** ](#4.-integrate-with-the-court)below), the escalation and enforcement criteria could be built into the logic of your 'Arbitrable' contract. {% endhint %} ### 2. Write a good 'Dispute Policy' The dispute policy is the primary document presented to the jurors to inform them on how to resolve a dispute. It is similar to a piece of real-world law referenced during cases to decide a dispute, but in this case only pertaining to your specific integration. Jurors will use three main categories of information to decide on their vote: 1. The dispute policy 2. The evidence provided (which can potentially be submitted by anyone on the internet) 3. If the above two are insufficient for deciding on the case, then the policies of the Court in question are considered. Writing a good dispute policy is therefore crucial to the fair and speedy resolution of a case, as it sets the backdrop against which the pieces of evidence are considered. {% hint style="info" %} Save time and avoid omissions by using our[ model policy here!](https://docs.google.com/document/u/1/d/1UYJ2mKSPhAn0-erAGa9MLiKQr25lpi-YPcMQrJyMOz4/copy?copyComments=true) Refer to the policy writing guide [here](/integrations/policy-writing-guide) if you need help adjusting it to your use case. {% endhint %} ### 3. Determine the Court parameters Once the above has been done, the next step is to decide on 1. The **Court** where you would want your cases to be arbitrated in 2. The **number of jurors** you want to draw into the first round of arbitration. Choosing the right court for your case ensures that it will be resolved in the quickest and most efficient manner. Do keep in mind the choices in this section directly affect the cost of arbitration; it is a function of the number of jurors drawn into the case, and the cost of involving an additional juror differs with each court. For an overview of the courts available on Ethereum Mainnet and their parameters, please refer to the community-managed [Klerosboard](https://klerosboard.com/court/?network=mainnet). {% hint style="info" %} A guide on the recommendation parameters for different use cases will be made available soon. For now, please reach out to us at for guidance. {% endhint %} ### 4. Integrate with the Court There are two ways to use Kleros Court for your dispute resolution: #### A. Smart contract integration The best way to integrate with Kleros is to invest in a smart contract integration with Kleros Court. While it takes work to write and audit an 'Arbitrable' smart contract (complying with the [**ERC-792**](/developer/arbitration-development/erc-792-arbitration-standard) standard), it does allow for a **trustless** integration and can fully address user concerns of centralized control or censorship. There are two ways to go about it: 1. **A fully ERC-792 compliant integration**, in which the full integration guide for this technical integration can be found here: [Smart contract integration with Kleros Court (Arbitrator)](/integrations/types-of-integrations/1.-dispute-resolution-integration-plan/smart-contract-integration) 2. **A** **greatly simplified variant of the ERC-792 integration** using an ['arbitrable-proxy' contract](/developer/arbitration-development/arbitrable-proxy), in which the evidence and appeal logic management and UI components are outsourced to Kleros-written smart contracts and frontends. All you need to do is for your pseudo-Arbitrable contact to call the `createDispute` function and poll for the ruling from the arbitrable-proxy afterwards. #### B. A standalone 'Recognition-of-Jurisdiction' (RoJ) integrations Sometimes there might be reasons why a full smart contract integration is not feasible for you (yet): * The case involves an off-chain dispute that cannot be trustlessly integrated with Kleros (e.g. off-chain video game disputes, real-world arbitration cases). * Kleros Court is not (yet) available on the chain/L2 you are on. * There are no resources to perform the full smart contract integration in the near term. * You prefer to test out the process with Kleros before investing development resources. In such cases, you can start with a simple Recognition-of-Jurisdiction (aka **RoJ**) setup in which disputes are created 'standalone' on [resolve.kleros.io](https://resolve.kleros.io/), and your service/platform simply pledges (to your users) to enforce the ruling of Kleros. While this is not a trustless integration method, it does allow you to introduce Kleros's rulings into your dispute resolution process very quickly, and allows you to test usage before investing in a full smart contract integration. ### 5. Communicate all the above to your users Once all the above are done, it is time to communicate the involvement of Kleros in the dispute resolution processes of your platform. This is essential for the smooth operations of your dispute resolution process and reduces any potential confusion when disputes eventually arise. This includes but is not limited to: 1. Ensuring that the dispute policy is publicly available and pinned using an immutable file storage system (e.g. [IPFS](https://ipfs.io/)) 2. Publishing and communicating the **escalation** and **enforcement** criteria. 3. Inform users on how to submit additional evidence and raise appeals (if applicable for your integration). Once all the above are done, you are ready to go live with Kleros! {% hint style="info" %} Reminder: To help you keep track of your integration process, click [**here**](https://docs.google.com/document/d/11HUXGV25cy_DMKXJvIn7LeAGBjY7ohXtO5uNN_C9wI0/copy?copyComments=true) to make a copy of our model integration plan! {% endhint %} ## Ready-made integrations Kleros Court has integrations with various ready-made integrations, built either by ourselves or one of our channel partners. ### Escrow For the usage of Kleros Court to decide if assets in escrow should be released, check out [Kleros Escrow](/products/escrow), which can be used [standalone](http://escrow.kleros.io) or integrated by calling its [smart contracts](https://github.com/kleros/kleros-interaction/tree/master/contracts/standard/arbitration). ### (Optimistic) Oracle solutions Kleros has a close integration with [Reality.eth](https://reality.eth.link/) (formerly Realitio), acting as an arbitrator to rectify oracle results in case the results are contested. Check out the full details in the page here: [How to use Reality.eth + Kleros as an oracle](/integrations/types-of-integrations/1.-dispute-resolution-integration-plan/channel-partners/how-to-use-reality.eth-+-kleros-as-an-oracle) ### Securing Snapshot votes Gnosis's [Zodiac Reality Module](https://gnosis.github.io/zodiac/docs/tutorial-module-reality/get-started/) makes use of the Reality+Kleros integration mentioned above to securely translate [Snapshot](https://snapshot.org/) voting results into on-chain transactions. ## Integration tools If you are performing a smart contract integration, you can use the centralized arbitrator below to test your integration: [Centralized Arbitrator](/integrations/types-of-integrations/1.-dispute-resolution-integration-plan/integration-tools/centralized-arbitrator) # Smart contract integration with Kleros Court (Arbitrator) When you want to integrate your smart contract with Kleros Court for a fully trustless integration. Kleros Court is the implementation of an arbitrator as per the [Arbitration standard](https://kleros.gitbook.io/docs/developer/erc-792-arbitration-standard) we developed. Most integrations consist in building or customizing an Arbitrable app so it can request arbitration to Kleros Court. Once you integrate with the Arbitration standard, you (or your users) will be able to choose any arbitrator that follows the standard to solve disputes, including Kleros. ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-fa1e7adaceedf0ea6558ee71156d9c94bee57591%2Fimage%20\(48\)%20\(3\)%20\(3\)%20\(3\)%20\(2\)%20\(1\).png?alt=media) You can build an arbitrable smart contract or ensure your existing smart contracts are compliant with the Arbitrable interface: * From scratch by applying the [Arbitration standard](https://kleros.gitbook.io/docs/developer/erc-792-arbitration-standard) (and/or using the [Archon library](https://kleros.gitbook.io/docs/developer/archon-ethereum-arbitration-standard-api)), * By customizing one of our [examples](https://github.com/kleros/erc-792/tree/master/contracts/examples) or looking at[ live integrations](https://kleros.gitbook.io/docs/integrations/live-and-upcoming-integrations), * By working with [Cooperative Kleros](mailto:contact@kleros.io) to adapt yours to the standard or creating a connector, ## Create/Modify the Arbitrable app to be integrated with Kleros Court If you want to integrate with Kleros for dispute resolution, you will have to create an `Arbitrable` smart contract as per the[ Arbitration Standard](https://kleros.gitbook.io/docs/developer/erc-792-arbitration-standard) that will allow executing the following flow: ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-3331a8c00da79959a864b74c0e6f9c9eb520f7e5%2FFlow_Arbitrable%20Arbitrator%20Smart%20Contract.png?alt=media) In the `Arbitrable` contract, you will have to define at least: * the address of the `Arbitrator` contract (look at the top of this page for the addresses of Kleros Court Arbitrators. * Some extra data to set up the arbitration (that will specify the sub-court to be used and the number of vote required) * List of subcourt IDs below, * We recommend starting with 3 votes. * Script to generate the arbitrator extra data `generateArbitratorExtraData = (subcourtID, noOfVotes) => 0x${parseInt(subcourtID, 10).toString(16).padStart(64, "0") + parseInt(noOfVotes, 10).toString(16).padStart(64, "0")};` * (If appeals are allowed) Stake multipliers representing multipliers of the appeal cost that a party must pay for a new round (in basis points) {% hint style="info" %} **Kleros Court Deployments (Arbitrator)** * [Kleros Court (Arbitrator) on Ethereum Mainnet](https://etherscan.io/address/0x988b3a538b618c7a603e1c11ab82cd16dbe28069) * [Kleros Court (Arbitrator) on xDai](https://blockscout.com/xdai/mainnet/address/0x9C1dA9A04925bDfDedf0f6421bC7EEa8305F9002) * [Kleros Court (Arbitrator) on Sokol](https://blockscout.com/poa/sokol/address/0xb701ff19fBD9702DD7Ca099Ee7D0D42a2612baB5/) * [Kleros Court (Arbitrator) on Ethereum Ropsten](https://ropsten.etherscan.io/address/0x9643e91d3734b795e914a64169147b70876272ba) * [Kleros Court (Arbitrator) on Ethereum Kovan](https://kovan.etherscan.io/address/0x60b2abfdfad9c0873242f59f2a8c32a3cc682f80) {% endhint %} {% hint style="info" %} **List of Subcourt IDs (Ethereum Mainnet)**\ \ The General Court ID is 0. 1. Blockchain 2. Non-Technical 3. Token Listing 4. Technical 5. Marketing Services 6. English Language 7. Video Production 8. Onboarding 9. Curation 10. Data Analysis 11. Statistical Modeling 12. Curation (Medium) 13. Spanish-English Translation 14. French-English Translation 15. Portuguese-English Translation 16. German-English Translation 17. Russian-English Translation 18. Korean-English Translation 19. Japanese-English Translation 20. Turkish-English Translation 21. Chinese-English Translation 22. Corte General en Espanol 23. Humanity Court {% endhint %} You can also check the subcourt IDs on community-owned [http://klerosboard.com/](http://klerosboard.com). Learn more about how to build an Arbitrable app integrated with the Kleros Court arbitrator by reading the ERC-792 Arbitration Standard linked below. {% content-ref url="/pages/-MQq2F9KT7vK9u2aUzqn" %} [ERC-792: Arbitration Standard](/developer/arbitration-development/erc-792-arbitration-standard) {% endcontent-ref %} ## Test it with the Centralized Arbitrator You can test your arbitrable app on mainnet and most testnets by deploying a centralized arbitrator that you control (= you can easily give rulings/decisions and set the arbitration fee) and testing the integration this way. More details about the arbitrator on the page linked below. {% content-ref url="/pages/-MWYnPiKLvSL2hFAaJfO" %} [Centralized Arbitrator](/integrations/types-of-integrations/1.-dispute-resolution-integration-plan/integration-tools/centralized-arbitrator) {% endcontent-ref %} For more details, please consult the [Arbitration Standard](https://kleros.gitbook.io/docs/developer/erc-792-arbitration-standard) documentation, have a look at the examples of implementations shared [here](https://github.com/kleros/erc-792/tree/master/contracts/examples), or contact us on Discord, Telegram, Slack, or send a mail to (links on the bottom left). # Use Cases Industry specific use cases of Kleros Kleros can be tailored to solve very industry and use case specific problems, which are explained in each of the pages below: {% content-ref url="/pages/-MRTxw9FpkBri53UjlLF" %} [DeFi Insurance](/integrations/types-of-integrations/1.-dispute-resolution-integration-plan/use-cases/defi-insurance) {% endcontent-ref %} {% content-ref url="/pages/-MRemMf2CVEXF7sxX9Xu" %} [Gaming](/integrations/types-of-integrations/1.-dispute-resolution-integration-plan/use-cases/gaming) {% endcontent-ref %} # DeFi Insurance Solutions for decentralized Insurance protocols ### Decentralizing claim management in DeFi Insurance An insurance claim is a formal request by a user to an insurance product for coverage or compensation for a covered loss or policy event. In the case of a decentralized finance insurance organization, a designated authority (DAO, Multi-sig, centralized resolver,...) should validate this claim (or deny it). If it is approved, the insurance contract will issue payment to the insured or an approved interested party on behalf of the insured. ![Insurance governance token holder that will see the value of its holdings decrease in case of a hack payout: “I don’t see any damage/hack here, sir.”](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-2bca0a63c424358ac00d9834d79fd1173c7995ca%2F0.png?alt=media) Legacy insurance companies often handle claims in a non-transparent and indisputable manner. The challenge for new DeFi Insurance products (apart from offering coverage for investments that could not be covered anywhere else) is therefore to offer a trust-minimized and fair mechanism to manage and arbitrate claims. ### The pitfalls of managing claim management through DAO governance The solution most often used by DeFi insurance projects is to delegate the challenges above to their DAO governance. While it might seem intuitively like a great solution, it is often fraught with dangers and pitfalls. Here are a few of them: * **Conflict of interest for the DAO token holders**\ There is a fundamental conflict of interest whenever a DAO governing an insurance protocol is tasked with its own claim approval process. On one hand, they have the duty to ensure rightful claims are paid out, thus allowing the protocol to serve its intended purpose. On the other hand, every successful claim chips away at their own capital staked in the protocol. Unless the voters/deciders in the claim approval process has no direct interest in the approval or rejection of a claim, the process cannot be said to be credibly neutral. * **Risk of creating a weaker single-use court system**\ If a DeFi protection app recreates a system where a few randomly selected governance token holders vote, then they will basically have to recreate a version of a dedicated arbitration system such as Kleros Courts. They will also not have any guarantee that the culture around their token will develop appropriately, as it takes time and effort to cultivate a community that is educated on jury duty in the decentralized world. * **DAO governance is weakened**\ The lock-up/staking of tokens is a cornerstone of any tokenomic design of an effective and honest decentralised court. What this means is that tokens locked up for court participation cannot be used for governance, and vice versa. Because of this, attempting to combine two use cases into a single token dramatically increases the vulnerability of both to 51% attacks. Furthermore, a court operating on the won't benefit from the network effects that Kleros has through working with a huge network of token-holding juries, arbitrating for multiple DAOs. * **Community-wide vote fatigue**\ If an insurance project asks every token holder to vote on every claim ever raised, it will require a massive duplication of effort and might be plagued by low response rates progressively creating security issues in the form of claim validation vote that could easily be swayed by a single whale. If voting is made optional, the results could skew towards the goals of those with specific agendas that may not be in the interest of the community, opening the door for collusion or vote buying. Most DeFi insurance projects operate with a (semi-)centralized process that employs a multi-step voting process to manage their claims. The claims will first often go through a community-wide approval or rejection process before being reviewed by a final committee that acts as the final decision-maker. ![Common Claim Process Template for DeFi Insurance projects](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-d886628ec5f82137a35bf8503355db40caf7a797%2F1.png?alt=media) However, the fact that the first round of vote by the governance token holders can be overridden every time by a committee of a handful of experts without a possibility to challenge them can make the whole process look like decentralization theater. Some other DeFi protection initiatives will let the users directly choose which arbitrator they want for the protection contracts they just created. And finally, the rest will be based on an automated incident monitoring system keeping an eye on events that can be detected and published on-chain (like a DAO emergency shutdown or a stablecoin on-chain price feed going below a specific value). While these setups automate and decentralize the fact-finding aspects of an insurance claim, the decision of how much the claimable damages are remain something a problem that requires a dispute resolution process. ## Why Kleros is a better solution Kleros offers better decentralized solutions to the challenges mentioned above, which are explained in this section. ### Kleros as a fair and trustless Claim Arbitration System Kleros recommends a Claimant-Challenger model for decentralizing your claim management process: a solution that can be achieved using Kleros's [Dispute Resolver](https://resolve.kleros.io/), which allows claims and disputes from an insurance protocol to be passed on to the Kleros Courts for arbitration. An arbitrable Claim Management contract can be written to interface between the Kleros Courts and the insurance protocol's payout contracts, allowing the decisions of the jurors in the Kleros Courts to translate to decision on claims within a DeFi insurance protocol. The Claimant-Challenger model follows the standard request-challenge protocol with a crowdfunded appeal system, where the claim submitter registers the claim and anyone can challenge said claim, thus creating a dispute in Kleros Court. An insuree would then be able to submit a claim using that contract and to provide the information related to his claim. If their claim is challenged, a dispute will be opened in the relevant Kleros Court. If not challenged, the claim will be considered valid and a payout will be triggered. An illustration of this process can be seen below: ![The most commonly prescribed claims process for insurance protocols using Kleros.](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-f0594f7f091f79469fca8474c070dd5ac5341447%2FDefi%20Insurance%20Project_1.png?alt=media) The Claim Management contract also can be designed to go beyond just simple Approve/Reject decisions, incorporating functionalities such as the ability for counter-offers to claims to be raised by parties such as the DAO governance or designated claim oversight teams. By doing this, an insurance project will simplify its development efforts by focusing on just the insurance mechanisms, while outsourcing the arbitration process to a decentralized and uncorrelated system. In summary, in the case of claim systems using Kleros as Claims arbitrator, the final ruling will be made if: * no claim challenge has been raised * no appeal has been made after a previous decision by jurors * a decision has been made in the highest General Court with no more appeal possible. #### Incremental adoption of Kleros There are many ways to incorporate Kleros into your DeFi insurance protocol, and it is possible to only adopt the elements that add the most benefit now, and incrementally move towards a more comprehensive integration when the need arises. There are at least 4 ways at which Kleros can be integrated into a decentralized claims process: 1. As one of the arbitration systems that can be selected when deploying a coverage contract, 2. As one of the signatories in a multi-sig committee taking the final decision about a claim. 3. As a ruler of last resort for claimants to dispute the rulings of a DAO's governance/central committee. 4. As the single default source for ruling when a claim is challenged An additional complementary integration would be for insurance projects to share a single common registry of “official DeFi hacks/exploits” that could be built as a [Kleros Curate](https://kleros.io/curate/) list, and have automatic payouts tied to the acceptance of a new entry into the list. In conclusion, if you don’t want to reinvent the wheel and expose your project to badly designed dispute resolution incentives, you should [reach out to us](mailto:contact@kleros.io) to seamlessly integrate the Kleros dispute resolution protocol within your Insurance project. # Gaming Kleros as a Dispute Resolution Mechanism in MMOs: The Case of Bots of EVE Online > *Disputes in massively multiplayer online games often transcend the basic understanding of terms and conditions and require a complex understanding of social norms of the community. Kleros, as a general dispute resolution mechanism, may be an excellent tool in bridging this gap and empowering the players to tackle the problems of abuse in open world MMOs.* \ EVE Online, a science fiction based MMO originally launched in 2003 boasts an almost cult-like following. The entire universe of EVE is a brimming social experiment on a grand scale, with players controlling most of what happens within it. From player-owned corporations vying for power in certain sectors to grand scale space battles making the Battle of Endor look like a border clash, EVE Online is a unique universe where players take the reins of the military, economic and social aspects within the game. This form of environment thrives on a laissez-faire regulatory approach to players and their actions - scamming other players, for example, is a completely valid play style (a personal favorite is he case of the [EVE Investment Bank](https://news.softpedia.com/news/Eve-Online-Economy-Suffers-700-billion-ISK-Scam-33737.shtml), where “Cally” promised high investment returns to players who put their money in and then walked away with over 700 billion ISK, the in game currency). While this kind of an approach gives a lot of freedom to players *in game*, the creators of the game control all attempts at abuse of the system from the outside. One of the most prominent ways of cheating the game by non-legitimate means is using bots for specific purposes to increase your revenue. ![](https://blog.kleros.io/content/images/2019/04/7k6vYwWo.png) ## Replicants Go Rogue So, what is botting in EVE Online? The concept is quite simple - players can automate the actions of the ship they control to do trade manipulation, resource mining and other time consuming tasks which are in some games called “grinding”. This, in turn, gives these players an unfair advantage over others, but it also affects the in-game economy. ![An EVE Online mining fleet in action.](https://blog.kleros.io/content/images/2019/04/ew1gHhHM.jpeg) As most of the aspects of the game are player controlled, so is the production and trading in the markets. A sudden increase in revenue of certain players and groups of players inflates the economy and drives the prices of ships and other materiel upwards, effectively distorting it. The use of bots in EVE Online has been a problem which has plagued the game’s creator, CCP Games and in turn the players for years. For example, the EVE Online unofficial subreddit r/eve contains some [quite interesting testimonies by bot makers](https://www.reddit.com/r/Eve/comments/8yipyt/confession_of_a_botmaker/), as well as almost a steady flow of [outrage by players](https://www.reddit.com/r/Eve/comments/a3rwfn/a_comprehensive_guide_to_botting_in_vale_of_the/) faced with these issues. This is actually a problem which has even gone so far that it got covered by some of the [most prominent gaming magazines](https://www.pcgamer.com/bots-are-threatening-eve-onlines-economy-and-players-are-fed-up/). In their most recent response, EVE Online’s creators have [responded to the player’s pleas](https://www.eveonline.com/article/pjms25/security-update-q4-2018) by vowing to fight bots through moderation at every step in 2019. ## The Kleros Approach - Replicant Hunters A legitimate approach to resolving disputes in online environments must include serious understanding of social norms of the community, which in many cases supersedes the basic terms and conditions. This challenge often overwhelms the community moderators, who need to spend significant amounts of time understanding each individual claim of botting and come to a just decision. But, what if we allow the community to filter the claims of botting in order to make the jobs of moderators more easy? The Kleros platform was created to allow for the formation of decentralized curated blacklists, which would help in filtering justified from non justified claims of abuse in online interaction. We have already proposed a similar system for [fake news detection](https://blog.kleros.io/can-kleros-fight-fake-news/) and our [T2CR platform](https://blog.kleros.io/ethfinex-kleros-decentralized-token-listing/) has proven that this system does indeed work. ![](https://blog.kleros.io/content/images/2019/04/blade-runner-final-cut-1-1.jpg) ## The LAPD 2019 Blaster Let’s take [the example of a player](https://www.pcgamer.com/bots-are-threatening-eve-onlines-economy-and-players-are-fed-up/) who is flying in a wormhole and discovers a Nyx Gallente Carrier which, after detection, withdraws all fighters and warps to a safe location. Even though this carrier could in fact blast him to kingdom come, it retreats. This pattern repeats several times in surrounding sectors with several different carriers of the same type. The player records these flight patterns and manages to divulge that what he uncovered is indeed a botting ring. He sends the information to the Kleros subcourt in-game and posts a deposit alongside the evidence gathered for other players to see. Jurors, who are players themselves, chosen at random analyze this data and can do further checking in-game to find more proof of this kind of breach. ![The potential flow of a dispute.](https://blog.kleros.io/content/images/2019/04/egaming.jpg) After observing all proof, they decide without a shadow of a doubt that the Nyx Carrier botting ring is indeed real and pass their judgement. The case is closed and the moderators receive the judgement with all evidence needed to ban the players who have been participating in this wrongdoing. If his proof is not conclusive, or this kind of claim is indeed found to be frivolous, the original poster of the dispute loses his deposit and no action is taken towards the accused players. ## Empowering the Crowd The Kleros approach derives from the Justice as a Service concept, allowing the creation of dedicated subcourts for games such as EVE Online and automating dispute resolution, which can be used to guarantee a stronger feeling of ownership over digital assets to players and further bolster the game economy. With players already knowing what goes on in their universe and [being quite vocal about it](https://www.reddit.com/r/Eve/comments/a3rwfn/a_comprehensive_guide_to_botting_in_vale_of_the/), this kind of approach would be bringing value to the community in several ways. There is no one who better understands the nuances in social norms of the community than the players themselves. With the Kleros approach, players become a part of the decision making process and not just reporters of malfeasance. On the other hand, the power is distributed between the posters of disputes, jurors and moderators. This kind of private governance mechanism, based on cryptoeconomics gives players a heightened sense of ownership over the universe they participate in. Instead of being governed by unseen entities of game creators or an oligarchy of powerful players, they are given an instrument to govern themselves. By creating a transparent, blockchain based court, community norms can be studied in much more detail through observation of court history, which would set the guidelines for inappropriate behaviour in an organic way and shape the environment through precedence. Another key element would be that it would become easier to track down botters and botting rings and make it easier to put a stop to this kind of abuse. Online communities evolve rapidly and social norms develop with them. The classic, centralized, top-down approach works in systems that have significant resources to manage and control the entire environment and even then abuse simply becomes more sophisticated and increasingly difficult to control. Just take a look at Facebook, for example. It is exactly for this reason that it is important to put power in the hands of the users and, through a curated and managed process, allow them to track down the bot menace for the good of the universe. # Recognition of Jurisdiction Integration A guide on how to use Kleros as a standalone dispute resolution service. ## Introduction If you're interested in using the [**Kleros Court**](/products/court) for dispute resolution within your project/company with zero technical work, the Recognition of Jurisdiction Integration (RoJ) is a great alternative. This is especially useful for **Protocols or Companies that are:** * Interested in **testing out the workflow with Kleros** * **Traditional companies** (web 2 or web 2.5) that do not interact with the blockchain Completing the necessary documentation for a RoJ is a relatively short process, which shouldn't take more than a few weeks (or even a few days). \ To begin with the 3 steps, it's recommended to have had a call with a member of the Business Development team beforehand. If you're interested in scheduling an initial call, please contact Marcos at . Integrating Kleros into your dispute decision process will always involve 3 main steps and they are outlined below. {% hint style="info" %} To help you keep track of your integration process, click [**here**](https://docs.google.com/document/d/1dn27idjPIfRInrPUmdvL2nYN0BQ6HRIu7yjVjDlRHFY/edit?usp=sharing) to make a copy of our RoJ integration plan! {% endhint %} ## Key integration steps for RoJ Following these 3 steps in sequence will ensure that your integration is secure and runs smoothly for both you and your users. ### 1. Determine the conditions for submission and enforcement A RoJ integration with Kleros implies that you have chosen to submit all or some of the disputes that may arise on your platform to Kleros Courts. As with real-world courts, Kleros Court is only a dispute resolution system, and it is important to remember that our decentralized jury only takes care of the ruling on a dispute given certain facts/evidences and policy documents. **Enforcement of the ruling is out of scope for Kleros (in this type of integration), and needs to be carefully taken care of by your service/platform/dApp.** * **Submission criteria**: determining the circumstances under which disputes may be submitted to Kleros court. * Example: escalation is only allowed after a first round of dispute resolution has taken place within your platform, and the disputed amount does not exceed a certain value. * **Enforcement criteria**: what criteria need to be fulfilled for your platform/service to commit to enforcing a ruling from Kleros * Example: The partner (exchange, fintech company, etc.) makes a pledge to their customers to abide by the Kleros ruling. \ And the user retains the right to pursue traditional legal actions if they are not satisfied with the decision made by Kleros. ### 2. Write a good 'Dispute Policy' The dispute policy is a document that serves as the primary "law" for jurors, providing them with rules on resolving disputes. It operates similarly to legal statutes or laws in real-world cases, tailored specifically to your integration. Jurors base their decisions on three key sources: * The dispute policy itself * The evidence presented by the parties * The policies of the Kleros courts. Writing a good dispute policy is essential for ensuring fair and expeditious dispute resolution. {% hint style="info" %} You can find our Policy Writing Questionnaire in our "[RoJ Integration Plan](https://docs.google.com/document/d/1dn27idjPIfRInrPUmdvL2nYN0BQ6HRIu7yjVjDlRHFY/edit?usp=sharing)" (mentioned above). Based on your feedback, the Kleros team will provide a first draft, subject to an iterative and collaborative process to create the best dispute policy possible. {% endhint %} ### 3. Communicate all the above to your users Once all the above are done, it is time to communicate the involvement of Kleros in the dispute resolution processes of your platform. This is essential for the smooth operations of your dispute resolution process and reduces any potential confusion when disputes eventually arise. This includes but is not limited to: 1. Ensuring that the dispute policy is publicly available and pinned using an immutable file storage system (e.g. [IPFS](https://ipfs.io/)) 2. Publishing and communicating the **escalation** and **enforcement** criteria. {% hint style="info" %} Please reach out to us at once you are done and we will advice you on the right court to use. {% endhint %} Once all the above are done, you are ready to go live with Kleros! *For more information about this type of integrations with Kleros, you can visit our* [*page on Notion: Web 2.0 companies.*](https://www.notion.so/kleros/Web-2-0-companies-635bc6949764444dadf6f2ae94d307b9?pvs=4) # Integración por Reconocimiento de Jurisdicción Una guía sobre cómo usar Kleros como un servicio independiente de resolución de disputas. ## Introducción Si está interesado en usar la [**Corte de Kleros**](/products/court) para la resolución de disputas dentro de su proyecto/empresa sin trabajo de desarrolladores/programadores, la Integración por Reconocimiento de Jurisdicción (RoJ) es una gran alternativa. Esto es especialmente útil para **Protocolos o Empresas que:** * Estén operando en **cadenas distintas a Ethereum y Gnosis Chain** (donde Kleros ofrece soporte nativo). * Interesadas en **probar el flujo de trabajo con Kleros** sin invertir en una integración técnica. * **Empresas tradicionales** (web 2 o web 2.5) que no interactúan con la cadena de bloques. Completar la documentación necesaria para una RoJ es un proceso relativamente breve, que no debería llevar más de unas pocas semanas (o incluso unos pocos días). Para comenzar con los 3 pasos, se recomienda haber tenido una llamada con un miembro del equipo de Desarrollo de Negocios previamente. Si estás interesado en programar una llamada inicial, por favor contacta a Marcos en . Integrar Kleros en tu proceso de toma de decisiones en disputas siempre implicará 3 pasos principales y están detallados a continuación. {% hint style="info" %} ¡[Haz clic aquí](https://docs.google.com/document/d/1dn27idjPIfRInrPUmdvL2nYN0BQ6HRIu7yjVjDlRHFY/edit?usp=sharing) para hacer una copia de nuestro plan de integración por RoJ! Esto te ayudará a llevar un seguimiento de tu proceso de integración, {% endhint %} ## Pasos clave para la integración por RoJ Siguiendo estos 3 pasos en secuencia asegurará que su integración sea segura y funcione sin problemas tanto para usted como para sus usuarios. ### 1. Determinar las condiciones para envío y ejecución Una integración de RoJ con Kleros implica que has decidido someter todos o algunos de los conflictos que puedan surgir en tu plataforma a los Tribunales de Kleros. Al igual que en los tribunales del mundo real, el Tribunal de Kleros es solo un sistema de resolución de disputas, y es importante recordar que nuestro jurado descentralizado solo se encarga de emitir un veredicto sobre un conflicto dado ciertos hechos/evidencias y documentos de política. **La ejecución del veredicto queda fuera del alcance de Kleros (en este tipo de integración) y debe ser cuidadosamente manejada por su servicio, plataforma o dApp.** * **Criterio de envío:** Determinar las circunstancias bajo las cuales las disputas pueden ser sometidas al tribunal de Kleros. * Ejemplo: El envío de casos, solo está permitida después de que se haya llevado a cabo una primera ronda de resolución de disputas dentro de tu plataforma, y el monto en disputa no exceda cierto valor. * **Criterio de ejecución:** Qué criterios deben cumplirse para que tu plataforma/servicio se comprometa a hacer cumplir un fallo de Kleros. * Ejemplo: El socio (Exchange, Banco Digital, etc.) se compromete con sus clientes a acatar el fallo de Kleros. Y el usuario conserva el derecho a emprender acciones legales tradicionales si no está satisfecho con la decisión tomada por Kleros. ### 2. Escribir una buena 'Política de Disputas' La política de disputas es un documento que sirve como la principal "ley" para los jurados, proporcionándoles reglas sobre la resolución de disputas. Opera de manera similar a estatutos legales o leyes en casos del mundo real, adaptados específicamente a tu integración. Los jurados basan sus decisiones en tres fuentes clave: * La política de disputas en sí misma. * Las pruebas presentadas por las partes. * Las políticas de los tribunales de Kleros. Escribir una buena política de disputas es esencial para garantizar una resolución justa y expedita de las disputas. {% hint style="info" %} Puedes encontrar nuestro Cuestionario para Escritura de Políticas en nuestro "[Plan de Integración por RoJ](https://docs.google.com/document/d/1WdS7dOR1prbj-2Aks14UAMgvVgxI9dVCf97vvuF4nJE/edit?usp=sharing)" (mencionado anteriormente). Basándonos en tus comentarios, el equipo de Kleros proporcionará un primer borrador, sujeto a un proceso iterativo y colaborativo para crear la mejor política de disputas posible. {% endhint %} ### 3. Comunicar todo lo anterior a tus usuarios: Una vez que se hayan completado todos los pasos anteriores, es el momento de comunicar la participación de Kleros en los procesos de resolución de disputas de tu plataforma. Esto es esencial para el funcionamiento fluido de tu proceso de resolución de disputas y reduce cualquier confusión potencial cuando las disputas surjan eventualmente. Esto incluye, pero no se limita a: 1. Asegurar que la política de disputas esté públicamente disponible y fijada utilizando un sistema de almacenamiento de archivos inmutable (por ejemplo, [IPFS](https://ipfs.io/)). 2. Publicar y comunicar los criterios de **envío** y **ejecución**. {% hint style="info" %} Por favor, contáctanos en una vez que hayas completado estos pasos y te asesoraremos sobre el tribunal adecuado a utilizar. {% endhint %} ¡Una vez que se hayan completado todos los pasos anteriores, estarás listo para poner en marcha Kleros! Para obtener más información sobre este tipo de integraciones con Kleros, puedes visitar [nuestra página en Notion: Empresas Web 2.0.](https://www.notion.so/kleros/Empresas-Web-2-0-en-Espa-ol-e38a90b4f94a440d9018aca712cddf53?pvs=4) # Channel partners Ready-made integrations for various use cases # How to use Reality.eth + Kleros as an oracle When you want your app to get data from a subjective oracle In use cases where a subjective oracle is required to give an answer on-chain about the occurrence of an event (e.g.: Prediction Markets, DAO Governance, etc...), your application might want to use the combination of [Reality.eth](https://reality.eth.link/) bond escalation mechanism with Kleros arbitration services to have a decentralized and fair source of truth. [Learn more about this use case](https://kleros.gitbook.io/docs/products/oracle) ### Architecture ![High-level architecture overview of an app using Reality.eth + Kleros as an oracle](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-d086b5709a3e8e6bca4c1b867b60a103f5c48a57%2FUntitled%20Diagram%20\(2\).png?alt=media) * **Your app requiring a subjective oracle** This is your smart contract that will only interact directly with Reality.eth contract. * **Reality.eth** Bond escalation mechanism contract where anyone can submit a question with a required minimum bond to submit answers. It is possible to request arbitration by a 3rd party at any point after a first answer is submitted. [Documentation](https://reality.eth.link/app/docs/html) - [Github](https://github.com/realitio/realitio-contracts/tree/master/truffle/contracts) * **Reality.eth < > Kleros Arbitrator proxy** Contract acting as a proxy between Reality.eth and Kleros Court contract. It acts as a Reality.eth arbitrator by creating corresponding disputes in Kleros Courts and submitting the final ruling as an answer in the proper format. This contract is configured with a number of initial votes required and a specific sub-court where the dispute will be raised (ex: 5 initial votes by jurors in Blockchain > Technical court). You can use one already used by other apps or ask the cooperative Kleros team to deploy a new one fit for your needs. [Github](https://github.com/kleros/realitio-arbitrator-with-appeals) * **Kleros** [Kleros Court](https://kleros.gitbook.io/docs/products/court) contract that will adjudicate on the dispute by drawing jurors and publishing a final ruling about the case. ### Requirements To use this service, you just need to ensure that: * your smart contract is compatible with the Reality.eth contract interface (check their [documentation](https://reality.eth.link/app/docs/html/contracts.html) and [repo](https://github.com/realitio/realitio-contracts/tree/master/truffle/contracts)) * If your contract is in development, Cooperative Kleros team can support you in making it compatible. * If your contract is already live, Cooperative Kleros team can support you in building a connector for it. * you submit the address of the Reality.eth<>Kleros arbitrator proxy you want to use as `arbitrator`when you ask a question. The arbitrator proxy will be set up with an initaial number of votes to be requested and a specific subcourt in whichcases will be raised. The Cooperative Kleros team can help select the right arbitrator for your use case or deploy a new one for you. ```typescript function askQuestion ( uint256 template_id, string question, address arbitrator, uint32 timeout, uint32 opening_ts, uint256 nonce ) external payable returns ( bytes32 ); ``` {% hint style="info" %} **Reality.eth <> Kleros Arbitrator Proxy deployments** * (Current version) Mainnet: General Court - 0x728cba71a3723caab33ea416cb46e2cc9215a596 * (Current version) Mainnet: Technical Court - 0xf72cfd1b34a91a64f9a98537fe63fbab7530adca * (Current version) Polygon: General Court - \ 0x5afa42b30955f137e10f89dfb5ef1542a186f90e * (Current version) Mumbai: General Court - \ 0xead0c9a4baeaf9b5221358539173602fa12b4b7d * (Current version) Kovan: Non-technical Court - 0xDEd12537dA82C1019b3CA1714A5d58B7c5c19A04 **Deprecated** * (Old version without appeals) [Mainnet](https://etherscan.io/address/0xd47f72a2d1d0E91b0Ec5e5f5d02B2dc26d00A14D) * 500 votes in general Court * (Old version without appeals) [Kovan](https://kovan.etherscan.io/address/0xa6ead513d05347138184324392d8ceb24c116118) {% endhint %} ### Sequence Diagram ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-7ee031f683c642ccad962d750a55ffd565e4febb%2FKleros%20Reality.png?alt=media) # Safe Zodiac integration This is a tutorial following a previous governance [blogpost](https://blog.kleros.io/kleros-x-safesnap/) and inspired by the [separation of powers in DAOs](https://www.youtube.com/watch?v=HDSZsl1Zk4c) talk given by Jimmy Ragosa at the ETHCC4. Here, you will learn how to make your DAO fully decentralized using: * [Gnosis Safe](https://gnosis-safe.io/): one of the leading multi-signature wallets used by companies to manage their crypto assets. * [Snapshot](https://snapshot.org/#/): a platform widely used for off-chain vote signaling. * [Zodiac](https://gnosis.github.io/zodiac/docs/tutorial-module-reality/get-started/): a Gnosis Safe module that allows trustless on-chain execution of off-chain votes using [Realitio](https://reality.eth.link/) (an escalation-game-based oracle). * [Kleros](https://kleros.io/): the decentralized dispute resolution protocol and the final piece of this governance system puzzle, as it secures the Realitio outcome. ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-febf8fe4c49c9f9bcf3bbcddf6aeab34b1aa0774%2FSeparation-of-powers.png?alt=media) ## Motivation You might be wondering why do we need so many blocks to achieve decentralized governance. Let's imagine that your project's treasury and smart contracts are managed by a multisig owned by team members. Furthermore, its token holders can use the project's Snapshot space to vote proposals, which should be carried out if successful, technically feasible and aligned with the project's mission. The big question is how do token holders make sure that the multisig owners will act accordingly. We can interpret this as a power play between an executive team performing actions and a legislative branch voting about what actions should be taken. The missing piece is a process secured by the equivalent to the judiciary power, which enforces the token holders decisions on-chain. Here is where Zodiac and Kleros come in. ## Getting started *If your DAO is already using Snapshot, Zodiac and Safesnap but without any arbitrator to resolve disputes, jump to* [*Adding Kleros to an Existing DAO*](#just-use-kleros)*.* Before starting to integrate Zodiac and Kleros, you will need a Gnosis Safe (learn more about it [here](https://gnosis-safe.io/#getting-started)) and an ENS domain, which must refer to your DAO's Snapshot space. For testing purposes, the [Safe App on rinkeby](https://rinkeby.gnosis-safe.io/) and any ENS name can be used. In short, Zodiac allows anyone to propose on-chain transactions that will be executed by the DAO. Whether each batch of transactions gets executed or not depends on the Realitio's outcome, based on the DAO's proposal rules. Everyone can participate in Realitio by providing an answer with a bond in ETH or in the DAO's token and request arbitration for disputed proposals. ## Zodiac Setup and Safesnap Integration A detailed guide on Zodiac setup can be found [here](https://gnosis.github.io/zodiac/docs/tutorial-module-reality/get-started). When setting the parameters, make sure to select Kleros in the arbitrator field. If no arbitrator is set, Realitio will resolve disputed proposals in favor of the highest bond submitted instead of using a third party dispute resolution protocol like Kleros. Alternatively to the Zodiac documentation, you can follow this video tutorial to set up the module. Once Zodiac is set up and [the Safesnap plugin was added to Snapshot](https://gnosis.github.io/zodiac/docs/tutorial-module-reality/integrate-snapshot), you can start testing proposals. Check also the following video guide on how to create executable proposals and process them after voting has ended: ## Adding Kleros to an Existing DAO If your DAO is already using Zodiac but no arbitrator has been set yet, you can do that as follows. Go to the Zodiac module on the Gnosis UI ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-4fe7a76d96e3aea7499e1698c8331128cfafe317%2FsetArbitrator.png?alt=media) Go to your module and under the "Write Contract" tab, select the setArbitrator function from the dropdown and, in the arbitrator field, paste the address of the Realitio Arbitration Proxy contract (Ethereum Mainnet: 0xf72CfD1B34a91A64f9A98537fe63FBaB7530AdcA). This proxy supports the Realitio interface and adds some features to the arbitration process, for example, allowing appeals to be crowdfunded. Once executed, Kleros is integrated into your DAO governance. Make sure to have governance guidelines written down and available, either at the DAO's ENS or somewhere clearly visible to the DAO (for an example check the [Proof of Humanity governance process](https://gov.proofofhumanity.id/t/hip-5-adopt-a-proper-poh-dao-governance-process-to-ensure-hip-quality/393)). ## Removing Gnosis Safe Signers There is one final thing we need to do to make the DAO truly decentralized. The Safe signers still have control over the multisig and some privileges over the SafeSnap module (like changing the arbitrator, question timeout, etc.). Let's remove those. Go to "Settings" --> "Owners" and remove all signers of the multisig except for yourself. It's not possible to have an ownerless Safe. For this reason, the remaining owner (you) has to be replaced by the Zodiac module address. Once this is done, it will be only possible to interact with the DAO's Safe through the Zodiac module, i.e. via governance. ## More About Kleros There are some important reasons why your governance system should be using Kleros as arbitrator. First off, a good arbitrator should be hard to attack. At the time of writing, Kleros courts have 150M PNK (\~4M USD) of stakes and roughly 800 active jurors. A substantial input of money over a sustained period of time would have to be invested to bend a court decision and, even if someone achieves to do so, it would probably be at a huge loss. For an in depth read go to [Why Kleros Need a Native Token](https://medium.com/kleros/why-kleros-needs-a-native-token-5c6c6e39cdfe). In addition, since conception, Kleros courts have resolved over 1000 cases of wide variety. Check the [Famous Kleros Cases](https://kleros.gitbook.io/docs/products/court/famous-kleros-cases) to see some examples. Kleros courts are active and have built a strong reputation. A good arbitrator should also be consistent over time, building jurisprudence as disputes get resolved while paying close attention to evidence and policy. This has especially been seen in the [Tokens registry](https://tokens.kleros.io/tokens) and [Proof of Humanity](https://app.proofofhumanity.id/). The Kleros Court is currently used as the Judiciary branch of [the Kleros DAO, the Proof of Humanity DAO and the UBI DAO](https://governor.kleros.io/). Even though these DAO's use a different infrastructure that depends on the Kleros Governor, this is a good precedent of a well functioning decentralized governance system. # Kleros Reality Module From the Zodiac app within the Safe app, you can deploy a Kleros Snapshot Module. This is a wrapper of the already existing Reality Module, and will automatically deploy it using Kleros as arbitrator. This module is available in Mainnet, Gnosis Chain, and Polygon. ## Setup Open your Safe dashboard, and click on *Apps*, search *Zodiac*, and open it. Click on *Kleros Snapshot Module*. If you can't see it, it might mean your safe is in a different chain. Kleros is only available on Mainnet, Gnosis and Polygon. ![image](https://user-images.githubusercontent.com/40367733/238977515-9f96b906-57d2-4419-bd04-927d659a62c7.png) Fill in the information. Some guidelines: * *Timeout* is a setting that affects the questions that will be created in Reality. An answer will be considered true if it remains unchanged during this period, unless called to arbitration. * *Cooldown* is the period from the point the answer is final, to the point the transaction batch can be executed. This is used to prevent malicious answers that might have slipped through from causing immediate damage, by allowing potential victims to react. In order to prevent damage, parties using the Safe are expected to stay vigilant and regularly pay attention to questions created by this module, as anyone is able to create them, without going through a Snapshot proposal. * *Expiration* is how long until an accepted transaction batch becomes too outdated to be executed. * *Bond* is the minimum amount required to post an answer to a question. Keeping it large makes it more punishing to attackers. Remember this amount is denominated in the chain's native token. ### Monitoring You can use Open Zeppelin Sentinel to monitor proposals. Take into account that anyone can submit a proposal to the Reality Module, so they are not to be trusted. With this monitoring system, you will be notified through various channels whenever a proposal is submitted. If a proposal turns out to be malicious, it must be countered through rejecting it's validity in the reality.eth question it will create. ![image](https://user-images.githubusercontent.com/40367733/238977898-1597d303-c755-4fe1-816b-7710179ab89c.png) ## SafeSnap If you encountered this warning: > *Install SafeSnap after creating the module* it means one of the following: * The controller of the ENS is not the Safe. * You are not in Mainnet. From here, you have two options. Most of the time, you will want to install SafeSnap manually. ### Have the Safe in control of the Snapshot Space This is only supported if you are in Mainnet. * Don't do this if you're just testing. * Don't do this if you're planning on decentralizing later. You can do it later when you're ready. * Do this if you know what you're doing, and you want to decentralize immediately by removing all the signers of the Safe later. * This will cost more gas. To do this, go to [the ENS frontend](https://app.ens.domains/) and type the ENS in. The deployment will work if you just *Set* the Controller of the ENS with the address of the Safe, but, if you want the Space to be fully in control of the Safe, and not in the control of anything else, you will need to *Transfer* the ENS itself. ### Configuring SafeSnap manually Just fill in the parameters normally, click on *Add Module*, and sign the resulting transactions. This will create a *Reality Module* with everything set up. After doing this, use a wallet you can use to change the Snapshot Space settings. Open Snapshot, and go to settings. Go to the Settings -> Advanced, *Add Plugin*. In `network`, type in the network id of the chain the Safe is in, quotes included. > Mainnet: `"1"`, Gnosis Chain: `"100"`, Polygon: `"137"` In `realityAddress`, paste in the address of the Reality Module. You can find this address in your Zodiac App. Check the screenshot below, the left side of the screen. ![image](https://user-images.githubusercontent.com/40367733/229247862-3b946415-f38b-434c-bb7f-cb517807e2c7.png) For the field `umaAddress`, you can either ignore it or remove the line. Check the sample config below for a deployment on Mainnet. ```json { "safes": [ { "network": "1", "realityAddress": "0x0811dE7b6CA6fF61C24eB8C6C885F44d1Bca4c28" } ] } ``` ## Missing `daorequirements` When you deploy the Reality Module, you will also setup a default template for the Reality questions that will be created. Within this template, there is a section that mentions the following: > and does it meet the requirements of the document referenced in the dao requirements record at ${dao}.eth? For reference, [here is a sample question created by the Reality Module](https://reality.eth.limo/app/#!/question/0x5b7dd1e86623548af054a4985f7fc8ccbb554e2c-0xeb3c667f6bb40ece6a17ba99e100e16fd2ba9f0723ad5a5289085b83b707d1f5). If this *dao requirements record* document does not exist, then it can be possible to resolve the question as *No*, since it is not possible to match the requirements of a document that does not exist. Alternatively, it could be resolve as *Yes*, since, if there are no requirements, that means there are also no restrictions. Questions can ultimately be applied for arbitration, by clicking *Apply for arbitration* in Reality. This has a fixed cost, but parties that have already posted an answer might be incentivized to pay this cost, instead of posting a new answer and doubling the bond. This fixed arbitration cost can change depending on the chain. The [Terms of Service of the Kleros Arbitrator for Reality](https://cdn.kleros.link/ipfs/QmXyo9M4Z2XY6Nw9UfuuUNzKXXNhvt24q6pejuN9RYWPMr/Reality_Module_Governance_Oracle-Question_Resolution_Policy.pdf) include some guidelines to limit the potential damage of not having set the `daorequirements` record, instructing the jurors to investigate the project, forum, etc, to find a reasonable frame of reference to find out these requirements, and assume some defaults if these requirements cannot be found. Still, this is a failsafe mechanism that should not be relied upon, at it can lead to different assumptions. In order to avoid this uncertainty, we advice adding a `daorequirements` record in the Snapshot Space ENS. To do so: * Create an acceptance document (plain text, pdf, anything is fine) * Proofread it to ensure it will not have unintended consequences. Kleros has experience writing policies and acceptance documents for subjective oracles, feel free to contact us if you want us to take a look. * Upload the document to IPFS. * Go to the [ENS frontend](https://app.ens.domains), access the ENS of the Snapshot Space, click on *Add/Edit Record*, and add a new record by selecting *text* on the left selector, typing in *daorequirements* in the right selector, and pasting the IPFS identifier. ![image](https://user-images.githubusercontent.com/128833886/229306507-035eb088-1806-40a6-a65b-957340fd0a04.png) For reference, [here is the ENS record of gnosis.eth](https://app.ens.domains/name/gnosis.eth/details), you can find a `daorequirements` record that points to a plaintext file with [a well defined acceptance criteria](https://ipfs.io/ipfs/QmZXAbYyDt7WUq2HqcvQrnxw7zXGPCGJvQXSrNsjik49Uy). ## How to Use the Reality Module After the SafeSnap plugin is installed in your space, there will be an extra step when creating proposals, that will allow the creator of the proposal to propose a batch of transaction batches. After you do, a proposal like this will be created. ![image](https://user-images.githubusercontent.com/128833886/229285087-af6c947d-ce56-4163-9656-2b2d918807e8.png) If the proposal passes, you will be allowed to begin execution. This will create a question in Reality. ![image](https://user-images.githubusercontent.com/128833886/229285220-73d17203-df57-438d-9286-a937cfb33c47.png) From here, you can answer the question directly, using *Set outcome*. ![image](https://user-images.githubusercontent.com/128833886/229285344-c5dbc5a9-ef39-4ceb-b944-fff0e63f8e19.png) You can handle it directly from Snapshot, or go to Reality by clicking *Question*. It is adviced to do it in Reality, as you will be able to read extra details, such the contents of the question, the terms of service of the arbitrator, and how long does it take for the current answer to be valid. When the question is finally resolved, execution will not be able to start until the *Cooldown period* passes. When it passes, you can use Snapshot to execute. Open the proposal that was accepted, and on the SafeSnap plugin on the bottom, you can execute the transaction. ## Legal entity for your DAO After activating a Zodiac Reality module, you may consider establishing a legal entity in jurisdictions that enable your DAO to manage a real-world legal entity. This step is beneficial for managing real-world assets and participating in legal contracts. To facilitate this, we recommend consulting with one of our partners who specialize in these arrangements: * [OtoCo](https://otoco.io/spinup) ## Further Information You can check [Zodiac Intergration](/integrations/types-of-integrations/1.-dispute-resolution-integration-plan/channel-partners/zodiac-integration) and [How to use Reality and Kleros as an Oracle](/integrations/types-of-integrations/1.-dispute-resolution-integration-plan/channel-partners/how-to-use-reality.eth-+-kleros-as-an-oracle). # Integration Tools A list of tools to help you with the integration of Kleros products {% content-ref url="/pages/-MWYnPiKLvSL2hFAaJfO" %} [Centralized Arbitrator](/integrations/types-of-integrations/1.-dispute-resolution-integration-plan/integration-tools/centralized-arbitrator) {% endcontent-ref %} {% content-ref url="/pages/b9w4jru4BoX0TtnyEWdg" %} [Dispute Resolver](/integrations/types-of-integrations/1.-dispute-resolution-integration-plan/integration-tools/dispute-resolver) {% endcontent-ref %} # Centralized Arbitrator Test your integration with Kleros Court easily 🔨 [Centralized Arbitrator](https://centralizedarbitrator.kleros.io)🔨\ \ The **Centralized Arbitrator** dashboard allows anyone to quickly deploy and operate a centralized arbitrator from a graphical user interface. This serves as a quick demonstration tool and can help to debug arbitrable apps trying to integrate with Kleros Court as an arbitrator. ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-3911f02047cf0378458826b3905183fb4c0c1b73%2Fimage.png?alt=media) ## How does it work? * You start by accessing the [dashboard](https://centralizedarbitrator.kleros.io) and connecting with a Metamask wallet set to the correct network you want to test on. {% hint style="info" %} **NETWORK COMPATIBILITY:** \ The Centralized Arbitrator can be used on: * Ethereum Mainnet * Ethereum Kovan * Ethereum Ropsten * Ethereum Rinkeby * *(You can request new testnet support to Kleros team)* {% endhint %} * Then, you choose between: * Deploying a new centralized arbitrator * Your current Ethereum address will be the owner and will be able to set rulings. * You have to set an arbitration fee amount that can be modified later on. * Selecting an already deployed centralized arbitrator * by inputting its address in the relevant field * or selecting it in the dropdown list if you already used it locally. ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-c5d78f5d6ea222226e51b7fdb1a79e0b8df43dea%2Fimage.png?alt=media) * You can change the arbitration fee required by your arbitrator if needed; ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-b5ff00ce0dad9ea15a26577c41616b03a11a786b%2Fimage%20\(53\).png?alt=media) * On the list below, you will be able to track incoming disputes from arbitrable apps, filter them by status and give rulings directly from the interface. ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-a7d770438cb33de363bb6492af12fd1b25187c66%2Fimage.png?alt=media) # Dispute Resolver Create, manage, and resolve disputes with Kleros Court's decentralized arbitration application 🔨 [Dispute Resolver](https://resolve.kleros.io/) 🔨 Kleros Dispute Resolver allows users to create, manage, and interact with disputes on the Kleros protocol. It provides a user-friendly interface for creating custom disputes, submitting evidence, funding appeals, and following the progress of disputes through the arbitration process. It allows users to: * Create disputes by filling out a form * List and view open disputes * See dispute details * Submit evidence * Fund appeals * Track dispute progress The application serves as a bridge between users and the Kleros Court system, allowing for decentralized arbitration without requiring users to write their own smart contracts. ### When to Use Dispute Resolver You should consider using Kleros Dispute Resolver in the following scenarios: 1. **Need for Neutral Arbitration**: When you need a neutral third party to resolve a dispute. 2. **Standalone Disputes**: When you want to create a dispute without integrating with an existing dApp or application. 3. **Off-chain Disputes**: For disputes involving off-chain activities that cannot be trustlessly integrated with Kleros. 4. **Simplified Arbitration Setup:** If Kleros Court isn't available on your blockchain, you can still use the Dispute Resolver app to create disputes. You'll get an official decision from Kleros judges, but without automatic enforcement. After receiving the ruling, you'll need to implement the decision manually in your own system. This approach gives you the benefit of Kleros's fair judgment while allowing you to handle enforcement according to your specific needs. 5. **Limited Resources**: When you lack the resources for a full smart contract integration. 6. **Custom Arbitrable Contracts**: For protocols with a custom arbitrable contract which don't have their own frontend to submit evidence or fund appeals. If the arbitrable contract implements the IDisputeResolver interface (available as an [NPM package](https://www.npmjs.com/package/@kleros/dispute-resolver-interface-contract)), it can take advantage of the Dispute Resolver frontend. ### Main Features
#### 1. Ongoing Disputes View all active disputes currently in progress within the system. This section allows you to browse disputes based on different phases: * Evidence submission * Commit phase * Voting phase * Appeal phase #### 2. Create Dispute The application provides a user-friendly form to create custom disputes. You can: * Select a specialized Kleros court * Choose the number of jurors * Define the dispute title, description, and category * Specify the question type (multiple choice, numeric, date) * Set ruling options * Add party information (aliases and addresses) * Upload supporting documentation
#### 3. Interact This section allows users to: * View detailed information about specific disputes * Submit evidence to ongoing disputes * Fund appeals for disputes in the appeal phase * Withdraw rewards after disputes are resolved
### Using the Application #### Connecting Your Wallet To interact with Dispute Resolver, you need to: 1. Have a Web3-compatible wallet (like MetaMask) installed 2. Connect your wallet to the application 3. Ensure you have sufficient funds for dispute creation and appeal funding #### Viewing Ongoing Disputes 1. Navigate to the "Ongoing Disputes" tab 2. Browse the list of active disputes 3. Filter disputes by their current phase if necessary 4. Click on a dispute to view more details

A sample Dispute

#### Creating a New Dispute 1. Navigate to the "Create" tab 2. Fill out the dispute creation form: * Select the appropriate court for your dispute * Specify the number of jurors (more jurors = higher cost but potentially more thorough arbitration) * Enter a title and description for the dispute * Select the question type (this determines how jurors will vote) * Enter the specific question to be resolved * Define the ruling options * Add party information if relevant * Upload any primary documentation (up to 4MB) 3. Review the arbitration cost displayed 4. Submit the form to create the dispute

A sample dispute for Klers Solidity court

**Question Types:** * **Multiple choice: single select**: Standard question with multiple options where jurors select one answer * **Multiple choice: multiple select**: Question where jurors can select multiple options * **Non-negative number**: Asks for a numerical answer (≥ 0) * **Date**: Asks for a date as an answer **Interacting with Existing Disputes** 1. Navigate to the "Interact" tab or click on a specific dispute 2. Review the dispute timeline showing its current phase 3. Explore the Dropdown sections for: * Appeal information * Question details * Evidence timeline

Interact with the sample dispute

#### Submitting Evidence 1. Open the dispute details page 2. Navigate to the "Evidence" section (available only during the Evidence phase) 3. Click to submit new evidence 4. Enter a title and description for your evidence 5. Upload supporting files if necessary 6. Specify which side your evidence supports 7. Submit the evidence
#### Funding Appeals 1. Open the dispute details page 2. Navigate to the "Appeal" section (available only during the appeal phase) 3. Choose which ruling option you want to support 4. View funding progress, suggested contribution, and potential return on investment 5. Enter the amount you wish to contribute 6. Confirm the transaction
When a ruling is appealed: * Both sides (winner and loser) need to provide funds * If only one side is fully funded, that side wins by default * If both sides are fully funded, the case goes to a new round with more jurors ### [Recognition of Jurisdiction (RoJ) Setup](/integrations/types-of-integrations/1.-dispute-resolution-integration-plan/use-cases/1.-dispute-resolution-integration-plan) For cases where the dispute ruling is not enforced onchain, you can use a Recognition-of-Jurisdiction (RoJ) setup: 1. Create standalone disputes on resolve.kleros.io 2. Your service/platform pledges to enforce Kleros rulings 3. Share the dispute link with relevant parties This approach allows you to: * Quickly introduce Kleros arbitration into your process * Test the system before investing in development * Handle off-chain disputes that cannot be trustlessly integrated ### For Developers with Custom Arbitrable Contracts If you have developed a custom arbitrable contract and need a user interface for your users to interact with disputes: 1. Implement the IDisputeResolver interface in your arbitrable contract (available as an [NPM package](https://www.npmjs.com/package/@kleros/dispute-resolver-interface-contract)) 2. The Dispute Resolver application will then be fully compatible with your contract 3. Users can use Dispute Resolver to submit evidence and fund appeals for disputes created through your contract 4. This eliminates the need to build your own dispute management frontend The `IDisputeResolver` interface standardizes crowdfunded appeals and evidence submission, making it easier to integrate with the Kleros ecosystem. # 2. Curated-data integration plan Solution plan for using the data from curated data registries created using Kleros ## Introduction While resolving disputes is the most direct way to integrate with Kleros, the Court can also be used to power the decentralized curation of information. Here are a few examples: * Contract metadata registries built with [**Kleros Curate**](/products/curate) * [Tokens registry](https://curate.kleros.io/tcr/100/0x70533554fe5c17CAf77fE530f77eAB933B92af60?ref=blog.kleros.io) * [Address tags registry](https://curate.kleros.io/tcr/100/0x66260C69d03837016d88c9877e61e08Ef74C59F2?ref=blog.kleros.io) * [Contract-Domain Name (CDN) registry](https://curate.kleros.io/tcr/100/0x957A53A994860BE4750810131d9c876b2f52d6E1?ref=blog.kleros.io) * [NFT registries](https://www.reddit.com/r/loopringorg/comments/srji2h/introducing_kleros_curated_nft_registry_a_work_in/) * Identity registries * [**Proof-of-Humanity**](https://www.proofofhumanity.id/) A full list of Kleros's existing integrations and partnerships can be found [here](/integrations/live-and-upcoming-integrations). Using Kleros's curated data registries always consists of the following steps, which are outlined below. {% hint style="info" %} To help you keep track of your integration process, click [**here**](https://docs.google.com/document/d/1al1JwX8LPQzNDKSmG_IIiLwqwtEVhnlGX9K_PI-o08M/copy?copyComments=true) to make a copy of our Curated Data model integration plan! {% endhint %} ## Key integration steps Following these steps in sequence will ensure that your integration is secure and runs smoothly for both you and your users. ### 1. Determine your data requirements Each curated registry of Kleros has a unique acceptance policy and field set for each entry onto the list. You can use one of the ready-made registries if it fits your needs. Otherwise, feel free to create your own list from scratch. #### 1.1 Using one of the existing registries The [main page](https://curate.kleros.io/) of Kleros Curate features a number of existing curated registries that have met certain quality standards in their policy and format. Note that the registries are specific to a chain, and you will see different lists on xDai/Gnosis chain than on Ethereum Mainnet. A few of the most important lists that are related to contract security metadata are: 1. [Tokens registry](https://curate.kleros.io/tcr/100/0x70533554fe5c17CAf77fE530f77eAB933B92af60?ref=blog.kleros.io) 2. [Address tag registry](https://curate.kleros.io/tcr/100/0x66260C69d03837016d88c9877e61e08Ef74C59F2?ref=blog.kleros.io) 3. [Contract-Domain Name mappings](https://curate.kleros.io/tcr/100/0x957A53A994860BE4750810131d9c876b2f52d6E1?ref=blog.kleros.io) There is also the [Proof-of-Humanity project](https://www.proofofhumanity.id/), which is a Sybil resistant curated registry of real humans (linked to their ETH addresses) on the Ethereum blockchain. #### 1.2 Creating your own TCR If none of the lists mentioned in the links above suit your needs, feel free to create your own registry by following the instructions here: [Kleros Curate Tutorial](/products/curate/kleros-curate-tutorial) {% hint style="info" %} Save time and avoid omissions by using our[ model TCR acceptance policy here!](https://docs.google.com/document/d/1R-CyzbJYVkIlRM6JSUX-Gm1QAHsHe6PDdJ1uxeoNfjs/copy?copyComments=true) Refer to the policy writing guide [here](/integrations/policy-writing-guide) if you need help adjusting it to your use case. {% endhint %} ### 2. Determine the method for data retrieval We recommend using one of the subgraphs built using [The Graph's](https://thegraph.com/en/) technology to query for the information one of the existing curated lists. [Retrieving information from Kleros Dapps](/integrations/types-of-integrations/2.-curated-data-integration-plan/interacting-with-arbitrable-app) ### 3. Build your frontend (if applicable) Once the curated registry has been decided/created, and the query for retrieving the data is settled, you can proceed to creating the frontend to display the information (if applicable for your use case). ### 4. Communicate all the above to your users Once all the above are done, it is time to communicate the involvement of Kleros in the dispute resolution processes of your platform to reduce any potential confusion around the processes. This includes but is not limited to: 1. Educating them on the decentralized nature of the curated registries, that the data is not under the control of Kleros (the organisation). 2. Educating them on how to [submit and challenge entries](/products/curate/kleros-curate-tutorial) to the curated registries in question. 3. Communicating the process for them to submit additional evidence and raise appeals (if supported). Once all the above are done, you are ready to go live with Kleros! # Retrieving information from Kleros Dapps Here you will find information on how to retrieve the information from Kleros Dapps like Curate, Proof of Humanity and the Court to power your own applications. ## Existing Kleros-managed registries ### 1. Contract security metadata registries Kleros uses three 3 registries on Gnosis Chain to curate information contracts across a number of EVM chains, including Ethereum, Gnosis, Polygon and Binance Smart Chain. The registry URLs and their registry contract addresses on Gnosis chain are as below: 1. [Tokens](https://curate.kleros.io/tcr/100/0x70533554fe5c17CAf77fE530f77eAB933B92af60?ref=blog.kleros.io) (0x70533554fe5c17CAf77fE530f77eAB933B92af60) 2. [Address Tags](https://curate.kleros.io/tcr/100/0x66260C69d03837016d88c9877e61e08Ef74C59F2?ref=blog.kleros.io) (0x66260C69d03837016d88c9877e61e08Ef74C59F2) 3. [Contract Domain Name](https://curate.kleros.io/tcr/100/0x957A53A994860BE4750810131d9c876b2f52d6E1?ref=blog.kleros.io) (0x957A53A994860BE4750810131d9c876b2f52d6E1) The data from all three registries can be pulled from the Subgraph endpoint of Kleros Curate on Gnosis chain: Here is a sample batched GraphQL query to retrieve the most important fields from each of these three registries for a single address: ```graphql { addressTags: litems(where:{ registry:"0x66260c69d03837016d88c9877e61e08ef74c59f2", key0_starts_with_nocase: $targetAddress, key0_ends_with_nocase: $targetAddress, status_in:[Registered, ClearingRequested] }, first: 1) { key0 #caipAddress key1 #publicName key2 #projectName key3 #infoLink } contractDomains: litems(where:{ registry:"0x957a53a994860be4750810131d9c876b2f52d6e1", key0_starts_with_nocase: $targetAddress, key0_ends_with_nocase: $targetAddress, key1: $domain, status_in:[Registered, ClearingRequested] }, first: 1) { key0 #caipAddress key1 #domain } tokens: litems(where:{ registry:"0x70533554fe5c17caf77fe530f77eab933b92af60", key0_starts_with_nocase: $targetAddress, key0_ends_with_nocase: $targetAddress, status_in:[Registered, ClearingRequested] }, first: 1) { key0 #caipAddress key1 #name key2 #symbol } } ``` #### A few things to note: * If the intention is to retrieve entries that have passed curation, only filter on statuses **`Registered`** and **`ClearingRequested`.** * The full data object for each of the entries in Curate are stored as a JSON file on IPFS. If you want to retrieve the entire file to get all the data available, you can use the `data` field to retrieve the IPFS URL, or use the `props` array to retrieve all the available key-value pairs. ### 2. Proof of Humanity The [Proof of Humanity registry](/products/proof-of-humanity) is a list of verified real humans on the blockchain. The subgraph endpoint for Proof of Humanity on Ethereum Mainnet is as follows:\ You can also query the contract directly deployed at [0xC5E9dDebb09Cd64DfaCab4011A0D5cEDaf7c9BDb](https://etherscan.io/address/0xc5e9ddebb09cd64dfacab4011a0d5cedaf7c9bdb). In this case, to check if an address is currently accepted in the registry, you can simply query the `isRegistered` function ([#L1029](https://github.com/Proof-Of-Humanity/Proof-Of-Humanity/blob/master/contracts/ProofOfHumanity.sol#L1029)). ## Arbitrary subgraph queries If you wish to pull data from custom registries or any other Dapps of Kleros, simply [query one of the subgraphs below](https://thegraph.com/docs/query-the-graph): {% hint style="info" %} **Kleros Arbitrable apps subgraphs** (Updated Sep 2024) * [Kleros Curate (Mainnet) subgraph](https://thegraph.com/explorer/subgraphs/A5oqWboEuDezwqpkaJjih4ckGhoHRoXZExqUbja2k1NQ?view=Query\&chain=arbitrum-one) * [Kleros Curate (Gnosis) subgraph](https://thegraph.com/explorer/subgraphs/9hHo5MpjpC1JqfD3BsgFnojGurXRHTrHWcUcZPPCo6m8?view=Query\&chain=arbitrum-one) * [Proof of Humanity v1 (Mainnet) subgraph](https://thegraph.com/explorer/subgraph/kleros/proof-of-humanity-mainnet) * [Kleros Court (Mainnet) subgraph](https://thegraph.com/explorer/subgraphs/Edg8H3AioJtYaih5PtfJhRNaERS6bU1XMn9dfPjEr5ao?view=Query\&chain=arbitrum-one) * [Kleros Court (Gnosis) subgraph](https://thegraph.com/explorer/subgraphs/AgBjAUhmpmg3wqebGX1nJgouEj4HjV8aed2HverETrYk?view=Query\&chain=arbitrum-one) {% endhint %} If no subgraph exists for the application you want to read from, you can request one to the Kleros team, or [define ](https://thegraph.com/docs/define-a-subgraph)and [deploy](https://thegraph.com/docs/deploy-a-subgraph) one. # 3. Kleros Oracle integration A comprehensive guide for integrating Reality.eth + Kleros oracle system to access reliable real-world data through decentralized verification and arbitration. ### Introduction Want your DApp to access reliable real-world information on-chain? The Reality.eth + Kleros oracle system provides a decentralized solution for subjective data verification through economic incentives and crowdsourced arbitration. This system combines two key protocols: * [Reality.eth](https://reality.eth.limo/) - The underlying oracle and bond escalation mechanism * [Kleros](https://court.kleros.io/) - The dispute resolution protocol ### How It Works The integration consists of two main parts: 1. **Your DApp** Your DApp only needs to interact with the Reality.eth contract directly * You submit questions with the appropriate arbitrator address * You retrieve final answers once they're available * No need to implement any arbitration logic in your code 2. **Oracle System** * The oracle system handles everything else behind the scenes: * Reality.eth: Manages questions, answers, and economic incentives through bond escalation * Arbitration Mechanism: When disputes arise, the Kleros Arbitrator Proxy creates a case in Kleros Court where jurors resolve the dispute, then reports the result back to Reality.eth {% hint style="info" %} This separation means your integration is simple - you only need to know how to ask questions and retrieve answers from Reality.eth. {% endhint %} ### Integration Options You have two ways to integrate with the Reality.eth + Kleros oracle: #### 1. Offchain Integration (Quick Testing) Use the [Reality.eth web interface](https://reality.eth.limo/) to submit questions and retrieve answers manually. This is ideal for: * Testing the system before full integration, learning how the system works * One-off questions that don't require automation #### 2. Onchain Integration (Production) Implement direct smart contract interaction with Reality.eth to programmatically: * Submit questions from your DApp * Retrieve verified answers * React to oracle responses {% hint style="info" %} For this approach, you'll need to thoroughly understand the Reality.eth interface. Check out the [official Reality.eth documentation](https://reality.eth.limo/app/docs/html/) and [Reality github](https://github.com/RealityETH/reality-eth-monorepo) {% endhint %} ### Resolution Flow The Reality.eth + Kleros system follows a push/pull model: 1. **Push**: Your DApp submits questions to Reality.eth 2. **Pull**: Your DApp later retrieves the verified answers The question can be resolved through two paths: #### Happy Path: Consensus Resolution 1. Someone submits an answer with a bond 2. No one challenges within the timeout period 3. The answer is finalized automatically 4. Your DApp can retrieve the result #### Unhappy Path: Arbitration Resolution 1. Someone submits an answer with a bond 2. Another user challenges with a higher bond 3. Bond escalation may continue until someone requests arbitration 4. The question gets frozen on Reality.eth 5. A dispute is created in Kleros Court 6. Evidence submission period begins 7. Jurors vote on the correct answer 8. The final ruling is submitted to Reality.eth 9. Your DApp can retrieve the arbitrated result {% hint style="info" %} **Important**: All interactions occur through the Reality.eth interface - you don't need to build separate interfaces for these different resolution paths. {% endhint %}
### Quick Start Guide #### Step 1: Configure Your DApp Your DApp only needs to interact with Reality.eth directly. Import the interface: ```solidity // SPDX-License-Identifier: MIT pragma solidity ^0.8.0; import "./IRealityETH.sol"; contract MyDApp { IRealityETH public realityETH; constructor(address _realityETHAddress) { realityETH = IRealityETH(_realityETHAddress); } // The rest of your contract... } ``` You can find the Reality.eth contract addresses under: #### Step 2: Ask Questions To submit a question to Reality.eth: ```solidity function askQuestion( uint256 templateID, string calldata question, address arbitrator, uint32 timeout, uint32 openingTimestamp, uint256 nonce ) external payable returns (bytes32 questionID) { // Choose the appropriate Kleros arbitrator proxy address for your network address arbitrator = 0xFf32eff53459485074b4Db14633252C9dcA3791A;// Example: Mainnet General Court // Any ETH sent with this transaction becomes the question reward return realityETH.askQuestion{value: msg.value}( templateID, question, arbitrator, timeout, openingTimestamp, nonce ); } ``` **Parameter Explanations:** * **templateID**: The question format template - commonly used values: * `0`: Boolean (Yes/No) questions * `1`: Numerical (uint) answers * `2`: Single-select multiple choice * `3`: Multiple-select multiple choice * `4`: Datetime responses * `5`: Hash type (new in v3.2) * **question**: The actual question with parameters matching the template format, separated by the unicode delimiter "␟": * Template 0 (bool): `"Did event X happen?␟category␟en"` * Template 1 (uint): `"What was the price of ETH on April 16, 2025?␟crypto␟en"` * Template 2 (single-select): `"Which team won the 2024 NBA Finals?␟"Lakers","Celtics","Bucks","Other"␟sports␟en"` * **arbitrator**: **arbitrator**: The address of the Kleros Arbitrator Proxy that will handle disputes. * **timeout**: Time in seconds the question will have after receiving an answer before it's automatically finalized. Typically around 1 day (86400 seconds). The contract enforces a maximum value of 365 days (31,536,000 seconds). * **openingTimestamp**: Unix timestamp defining the earliest time when answers can be submitted. Set to 0 if you want the question to be answerable immediately. * **nonce**: A user-supplied number to differentiate between identical questions with the same settings. Use 0 if you don't plan to ask the same question with identical parameters more than once. **Example** ```solidity // Ask with a 0.1 ETH reward bytes32 questionID = realityETH.askQuestion{value: 0.1 ether}( 0, // Boolean template "Did the S&P 500 close above 5000 on April 16, 2025?␟finance␟en", arbitratorAddress, 86400, // 24 hour timeout 0, // Answerable immediately 0 // Default nonce ); ``` #### Official Arbitrator Proxy Addresses The system supports same chain and cross-chain deployments (question on one chain, arbitration on another). * **Same-chain oracle and arbitration**: * **Ethereum Mainnet (General Court)**: `0xFf32eff53459485074b4Db14633252C9dcA3791A` * **Ethereum Mainnet (DAO Governance/Technical Court)**: `0xf72cfd1b34a91a64f9a98537fe63fbab7530adca` * **Sepolia Testnet**: `0x05b942faecfb3924970e3a28e0f230910cedff45` * **Cross-chain oracle and arbitration**: * Question and arbitration on different chains, aka cross-chain proxies: list of deployments [here](https://github.com/kleros/cross-chain-realitio-proxy/tree/master/contracts#deployments). #### Step 3: Retrieve Answers Once your question has been answered (either through consensus or arbitration), retrieve the answer: ```solidity function getAnswer(bytes32 questionID) external view returns (bytes32) { // This will revert if the question is not finalized return realityETH.resultFor(questionID); } // For safer access that won't revert: function isQuestionFinalized(bytes32 questionID) external view returns (bool) { try realityETH.resultFor(questionID) returns (bytes32) { return true; } catch { return false; } ``` ### Evidence Submission for Disputes When a Reality.eth question goes to arbitration, there's a crucial evidence submission period where parties can provide supporting materials to help jurors make informed decisions. #### Understanding the Evidence Timeline 1. **Question Posted**: Your question is submitted to Reality.eth 2. **Answer Phase**: Users submit answers with bonds 3. **Arbitration Requested**: Someone pays the arbitration fee to dispute an answer 4. **Evidence Period Begins**: A window opens for submitting evidence (typically 3-7 days) 5. **Voting Phase**: Kleros jurors review evidence and vote 6. **Final Ruling**: The decision is reported back to Reality.eth #### How to Submit Evidence Evidence submission happens through the Kleros Arbitrator Proxy contract, **not** through Reality.eth directly. **Method 1: Smart Contract Integration** ```solidity // Import the arbitrator proxy interface interface IKlerosArbitratorProxy { function submitEvidence( uint256 _questionID, string calldata _evidenceURI ) external; } contract MyDApp { IKlerosArbitratorProxy public arbitratorProxy; constructor(address _arbitratorProxyAddress) { arbitratorProxy = IKlerosArbitratorProxy(_arbitratorProxyAddress); } function submitEvidenceForQuestion( bytes32 questionID, string calldata evidenceURI ) external { // Convert questionID to uint256 for the arbitrator proxy uint256 questionIDUint = uint256(questionID); arbitratorProxy.submitEvidence(questionIDUint, evidenceURI); } } ``` **Method 2: Direct Contract Call** You can also submit evidence directly by calling the arbitrator proxy contract: ```solidity // Call submitEvidence on the proxy contract arbitratorProxy.submitEvidence( uint256(questionID), "/ipfs/QmYourEvidenceHash" ); ``` #### Evidence Format and Best Practices **Evidence URI Requirements:** * Must be a publicly accessible URL * IPFS links are recommended for decentralization: `/ipfs/QmHash` or `ipfs://QmHash` * Can also use traditional web hosting, but permanence is important **Evidence Content Guidelines:** Evidence should follow the ERC-1497 standard format:
```json { "fileURI": "/ipfs/QmScreenshotHash", "fileHash": "QmScreenshotHash", "name": "Evidence Supporting Yes", "description": "Official S&P website showing closing price of 5,127.43", "fileTypeExtension": "png" } ``` **For Supporting a "Yes" Answer:** ```json { "fileURI": "/ipfs/QmScreenshotHash", "fileHash": "QmScreenshotHash", "name": "Evidence Supporting Yes", "description": "Proof that the S&P 500 closed above 5000 on April 16, 2025 - Official S&P website showing closing price of 5,127.43", "fileTypeExtension": "png" } ``` **For Supporting a "No" Answer:** ```json { "fileURI": "/ipfs/QmCounterScreenshotHash", "fileHash": "QmCounterScreenshotHash", "name": "Evidence Supporting No", "description": "Proof that the S&P 500 did NOT close above 5000 on April 16, 2025 - Official S&P website showing closing price of 4,987.22", "fileTypeExtension": "png" } ``` #### Multiple Evidence Submissions * **Anyone can submit evidence** during the evidence period * **Multiple submissions are allowed** - you can submit additional evidence as you find it * **Both sides should submit** - supporters of different answers should provide their evidence * **Quality over quantity** - clear, authoritative evidence is more valuable than numerous weak sources #### Evidence Timing * Evidence periods length varies by court configuration * Check the specific arbitrator proxy settings for exact timing * Submit evidence **as early as possible** - don't wait until the last minute * Evidence can be submitted until the dispute moves to the voting phase #### Monitoring Evidence Submission You can monitor when evidence periods open by watching for events: ```solidity // Listen for Dispute events from the arbitrator proxy event Dispute( IArbitrator indexed _arbitrator, uint256 indexed _disputeID, uint256 _metaEvidenceID, uint256 _evidenceGroupID ); // Listen for Evidence events to see what others have submitted event Evidence( IArbitrator indexed _arbitrator, uint256 indexed _evidenceGroupID, address indexed _party, string _evidence ); ``` ### Technical Details #### Reality.eth + Kleros Arbitrator Proxy The Kleros Arbitrator Proxy: * Acts as an arbitrator for Reality.eth * Creates disputes in Kleros Court when arbitration is requested * Reports Kleros rulings back to Reality.eth in the proper format #### Kleros Court The Kleros Court: * Adjudicates on disputes by drawing jurors * Manages the crowdfunded appeals process * Publishes final rulings that are transmitted back to Reality.eth ### Working with the Kleros Oracle System #### Question Types and Templates The Reality.eth + Kleros oracle supports various question types: | Type | Description | Example | | --------------- | ---------------------------------------------- | --------------------------------------- | | Bool | Yes/No questions | Did event X happen? | | Uint | Numerical answers | How many votes did candidate Y receive? | | Single-select | Multiple choice with one answer | Which team won the championship? | | Multiple-select | Multiple choice with multiple possible answers | Which states voted Democrat? | | Datetime | Date/time responses | When did the event occur? | | Hash | Hash-based identification (new in v3.2) | Does hash X correspond to document Y? | Questions use templates to reduce gas costs. Built-in templates include: ``` [ ] 0: {"title": "%s", "type": "bool", "category": "%s", "lang": "%s"} 1: {"title": "%s", "type": "uint", "decimals": 18, "category": "%s", "lang": "%s"} 2: {"title": "%s", "type": "single-select", "outcomes": [%s], "category": "%s", "lang": "%s"} 3: {"title": "%s", "type": "multiple-select", "outcomes": [%s], "category": "%s", "lang": "%s"} 4: {"title": "%s", "type": "datetime", "category": "%s", "lang": "%s"} ``` \ You can create custom templates with `createTemplate()` or use the [Reality.eth Template Generator](https://reality.eth.link/app/template-generator). #### Interpreting Results Responses are returned as `bytes32`. Depending on the question type: * **Bool**: `1` (Yes), `0` (No), or `0xff...ff` (Invalid) * **Uint**: The number as bytes32, divided by `decimals` if specified * **Single-select**: Zero-indexed selection (0 for first option, 1 for second, etc.) * **Multiple-select**: One-indexed with bitwise addition (1 for first, 2 for second, 1+2=3 for both) * **Datetime**: Unix timestamp (seconds since 1970) * **Hash:** The submitted hash that matches the criteria Special values you may encounter: * `0xff...ff` (all f's): Invalid answer * `0xff...fe` (all f's except last digit): "Answered too early" - when a question needs more time ### Fees and Payments The Reality.eth + Kleros system involves several types of fees and payments, each with a specific purpose in the incentive mechanism: | **Fee type** | **Set by** | **Paid by** | **Deductions** | **Paid to** | | --------------- | ----------------- | ----------------------------- | ------------------- | ------------------------------------------------------------- | | Question Reward | Asker | Asker | None | Highest-bonded correct answerer\* | | Answer Bond | Answerer | Answerer | None | Returned if correct, or to next correct answerer if incorrect | | Takeover Fee | Previous answerer | Subsequent answerer | From answer rewards | Previous answerer | | Arbitration Fee | Arbitrator | Anyone requesting arbitration | None | Arbitrator | | Claim Fee | System (2.5%) | Claimer | From claimed amount | Burned | \*Except when settled by arbitration #### Question Reward * Set by sending ETH when calling `askQuestion()` * Any ETH or tokens provided with the askQuestion or askQuestionERC20 call will be used as a question reward, minus any fee the specified arbitrator requires when a new question is asked * Incentivizes correct answers * Paid to whoever provides the final accepted answer * If decided by arbitration, the arbitrator specifies who receives the reward * Higher rewards typically result in faster and more accurate answers #### Answer Bond * Backs the answerer's claim that their answer is correct * Set by the answerer, but must be at least twice the previous bond if there was a prior answer * Returned if the answer is correct * If incorrect, paid to the next answerer who supplies the correct answer #### Answer Takeover Fee * Compensates previous answerers when someone takes over a correct answer * Equal to the bond supplied by the last person who gave that answer * Paid to the last person who gave that answer * Deducted from payments that would otherwise be awarded for giving the correct answer #### Arbitration Fee * Paid to the arbitrator when requesting intervention * Set by the arbitrator * Paid by the user requesting arbitration (usually an answerer whose answer was replaced) #### Claim Fee * From Reality.eth v2.1 onwards * 2.5% of claimed bonds (except the final bond) is burned ### Kleros Oracle in Production * **Prediction Markets**: Seer, Polkamarkets/Foreland, and Omen use it to verify real-world event outcomes * **Optimistic Governance**: [Zodiac SafeSnap module](https://docs.kleros.io/integrations/types-of-integrations/1.-dispute-resolution-integration-plan/channel-partners/kleros-reality-module#safesnap) implements it for secure DAO proposal execution * **Content Moderation**: [Moderate/Susie bot](https://kleros.io/moderate) leverages it for decentralized content policy enforcement ### Advanced Topics #### Custom Primary Document for Arbitration For most DApp integrations, the standard [general document](https://ipfs.io/ipfs/QmaUr6hnSVxYD899xdcn2GUVtXVjXoSXKZbce3zFtGWw4H/Question_Resolution_Policy.pdf) works perfectly fine without any customization. However, in some specialized cases, you may need a custom primary document for arbitration. **When Is This Required?** A custom primary document becomes necessary when: 1. Your DApp has specific rules for how disputes should be judged 2. Resolving disputes requires specialized knowledge or context 3. You need a dedicated Kleros court for your application's disputes 4. The interpretation of answers in your context differs from standard interpretations **The Complete Scenario** If you need a custom primary document: 1. **Initial Assessment**: The Kleros team evaluates your use case to determine if standard arbitration guidelines are sufficient 2. **Document Creation**: You work with Kleros to create a document that: * Explains your application's context to jurors * Provides guidance on evaluating evidence * Defines specialized terminology * Establishes clear criteria for determining correct answers 3. **Deployment**: Kleros deploys a dedicated arbitrator proxy for your application with your primary document embedded as part of the proxy's metaevidence 4. **Usage**: When disputes go to arbitration, jurors use your guidelines to make decisions **Real-World Example: Seer Prediction Markets** Seer required a [custom primary document](https://ipfs.io/ipfs/QmPmRkXFUmzP4rq2YfD3wNwL8bg3WDxkYuvTP9A9UZm9gJ/seer-markets-resolution-policy.pdf) because they needed specific rules for handling complex market outcomes, edge cases like delayed events, and wanted to specify which information sources should be considered authoritative for their prediction markets. If you think your application might need this level of customization, the Kleros team can guide you through the process. ### Common Questions **Q: Does my DApp need to call the arbitrator proxy directly?** A: No! Your DApp only needs to interact with Reality.eth. The proxy handles communication between Reality.eth and Kleros. **Q: What happens if there's a dispute?** A: The dispute process is handled automatically between Reality.eth and Kleros via the arbitrator proxy. **Q: How can I make my question clearer for accurate answers?** A: Be specific, include resolution criteria, and specify a trusted information source if applicable. For example: "Did the S\&P 500 close above 5,000 on April 10, 2025, according to the official S\&P website?" **Q: If I don't want to use the Reality.eth frontend for my users, can I handle everything from my DApp** A: Yes, you can implement the full flow in your DApp, including submitting questions, providing answers, and requesting arbitration as needed. ### Need Help? Contact the Kleros team at if you need: * A custom arbitrator proxy deployment * Help with Reality.eth integration * Assistance with complex use cases # Policy writing guide A well-written policy is the cornerstone of an effective and secure dispute resolution setup Here are a number of tips on how to write a fair, clear and secure policy for your curated registry or dispute resolution process: ### Disambiguation If there are several parties involved in a dispute, it is important to define the terms used to refer to each of them at the start of the policy. {% hint style="info" %} Example: "For the purposes of this document, the party that purchases a service or goods will be referred to as the **Client** and the counter-party that offers the service or goods will be referred to as the **Provider**." {% endhint %} ### Clarifying the usage of modal verbs Define how modal verbs should be interpreted in the context of the dispute, as they can lead to ambiguity around obligations and permissions. {% hint style="info" %} Example: "The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119." {% endhint %} ### Make explicit what is allowed and not allowed Be clear and specific about what should and should not be admissible. If the policy is for a curated registry, also state what are the criteria for removing an entry from the list, as there might be other reasons (other than the absence of the criteria for inclusion) that needs to be made explicit. Where possible, give examples. {% hint style="info" %} Example: "Submissions on either chain must be considered independently and on their own merits. To be explicit, each pair of submissions in the following two examples must not be considered duplicates: * Tagging 0xdc6…3A35 as “Curve.fi: EURS/sEUR” on ETH Mainnet and in Gnosis. * Tagging 0xdc6…3A35 as “Curve.fi: EURS/sEUR v2” on ETH Mainnet and “Curve.fi: EURS/sEUR (v2)” on Gnosis." {% endhint %} ### When it comes to choices, less is more To reduce the chances of vote-splitting, it is important to reduce the number of choices available for jurors to pick. If possible, limit it to just 2 for most cases. # Live & Upcoming Integrations Overview of the Kleros ecosystem The Kleros ecosystem lives and breathes through the disputes brought back to the Court by all arbitrable apps integrated with it. Some are developed by the Cooperative Kleros team (see [Products section](/products/court)) but most are external projects plugging into the Kleros products to get arbitration/curation/oracle/escrow services. In total, we already have more than **60** partners either using our Court and products or participating in joint research on decentralized justice and governance solutions. ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2FounmIwqqXQWMYGessYLY%2Fimage.png?alt=media\&token=f3a0fe68-a1ef-45de-8ef8-203570114873) {% hint style="info" %} Check out the full Kleros Ecosystem page [**here**](https://www.notion.so/kleros/Kleros-ecosystem-f013376368364a5ebc0bbee176ed7eb1) featuring all of our 60+ partners and collaborators**,** or scroll on to read about a few of the highlights below. {% endhint %} ## Highlighted Integrations: ### Kleros products These dApps were developed by Kleros using our Court in the background. * [Proof of Humanity](https://kleros.gitbook.io/docs/products/proof-of-humanity) * [Tokens](https://kleros.gitbook.io/docs/products/tokens) * [Curate](https://kleros.gitbook.io/docs/products/curate) * [Escrow](https://kleros.gitbook.io/docs/products/escrow) * [Linguo](https://kleros.gitbook.io/docs/products/linguo) * [Governor](https://kleros.gitbook.io/docs/products/governor) * [Oracle](https://kleros.gitbook.io/docs/products/oracle) (in conjunction with [Reality.eth](https://reality.eth.link/)) ### ⚖️ Projects using Kleros arbitration directly ⚖️ ### Unslashed Finance [Unslashed Finance](https://unslashed.finance) is an insurance platform for DeFi protocols, wallets, and stablecoins. It uses Kleros arbitration to handle its reimbursement claims process in an unbiased and decentralized manner as anyone can make a claim or challenge a claim and the resulting disputes are solved in a Kleros subcourt. ### 🔮 Projects using Kleros arbitration through Reality.eth oracle 🔮 #### Omen The [Omen](https://omen.eth.link) prediction market (on Ethereum mainnet and xDai) uses the [Kleros Oracle](https://kleros.gitbook.io/docs/products/oracle) solution (Reality.eth (bond escalation) + Kleros Court (Arbitration)) to rule on the outcome of events that are being predicted in their markets. For example, Kleros jurors rules on famous disputes about the number of Covid deaths in the US in July 2020 ([Case 302](https://thedailychain.com/an-important-case-for-the-decentralized-world-with-kleros/)) and about the winner of 2020 US presidential election ([Case 532](https://twitter.com/jimmyragosa/status/1341293611682553856?lang=en)) #### Gnosis Safe SafeSnap The [Gnosis Safe](https://gnosis-safe.io) multi-sig wallet can be used for DAO governance purposes thanks to the [SafeSnap](https://blog.gnosis.pm/introducing-safesnap-the-first-in-a-decentralized-governance-tool-suite-for-the-gnosis-safe-ea67eb95c34f) module. This module is using the [Kleros Oracle](https://kleros.gitbook.io/docs/products/oracle) solution (Reality.eth (bond escalation) + Kleros Court (Arbitration)) to effectively enforce on-chain the implementation and triggering of the proposals voted on by the DAO on Snapshot. #### 1Inch [1Inch](https://1inch.io/) is a leading DeFi/DEX aggregator that has integrated the [Gnosis Zodiac Reality Module](https://gnosis.github.io/zodiac/docs/tutorial-module-reality/get-started/), with Kleros set as the arbitrator in case of oracle disputes on Reality.eth. #### PolkaMarkets​ [Polkamarkets](https://www.polkamarkets.com) is a gamified prediction market using the [Kleros Oracle](https://kleros.gitbook.io/docs/products/oracle) solution (Reality.eth (bond escalation) + Kleros Court (Arbitration)) to rule on the outcome of events that are being predicted in their markets. ### 📝 Projects using Kleros arbitration through Curate TCRs 📝 #### CLR.fund The [clr.fund](https://clr.fund) public goods funding protocol uses a [Kleros Curate](https://curate.kleros.io/tcr/0x2E3B10aBf091cdc53cC892A50daBDb432e220398) list to curate public goods projects that are eligible to receive donations through quadratic funding. It enables the open and fair filtering of non-public goods projects that would diminish the matching of donations for compliant projects. #### Omen The [Omen](https://omen.eth.link) prediction market (on Ethereum mainnet and xDai) uses a [Kleros Curate](https://curate.kleros.io/tcr/0xb72103eE8819F2480c25d306eEAb7c3382fBA612) list to curate "Verified Markets" that are well written according to acceptance criteria and to display a "Verified" badge next to them on their UI. It allows users to easily be reassured that they are not participating in a "tricky" market designed to fool the outcome shares buyers. ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-5d7187521f6db6dcc18680440124989de50563a9%2Fimage.png?alt=media) ### 🔵 Projects using Kleros arbitration through Tokens TCR 🔵 #### Uniswap / Sushiswap / Cowswap [Uniswap](https://uniswap.org), [Sushiswap](https://sushi.com) and [Cowswap ](https://cowswap.exchange)decentralized exchanges use [Kleros Tokens](https://tokens.kleros.io/tokens) as one of their token lists to be selected to trade on their UIs. This [token list](https://tokenlists.org/token-list?url=t2crtokens.eth) is the only one to be completely open, decentralized, and managed by the community. ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-f11153c9cd15757c53de0d61a2059c8766b79af8%2Fimage.png?alt=media) #### Paraswap [Paraswap ](https://paraswap.io/#/?network=ethereum)decentralized exchanges aggregator use [Kleros Tokens](https://tokens.kleros.io/tokens) as one of their **default** token lists. This [token list](https://tokenlists.org/token-list?url=t2crtokens.eth) is the only one to be completely open, decentralized, and managed by the community. #### Zerion [Zerion](https://app.zerion.io) DeFi portfolio management tool pulls data from Kleros Tokens to read the tokens held in your wallet and also uses it as a way to verify the correctness information about tokens displayed in its interface (if a token is in at least 2 lists *\[ex: Kleros + Coingecko]*, it earns a "Verified" badge.) ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-ab77fad2b797744acb69e53b87c599cf827a40b7%2Fimage.png?alt=media) #### Revoke.cash [Revoke.cash](https://kleros.gitbook.io/docs/products/tokens) is a tool allowing users to revoke ERC-20 allowances granted from their address to avoid malicious use of these allowances. It uses [Kleros Tokens](https://kleros.gitbook.io/docs/products/tokens) to identify tokens in the wallet connected. ### 🔵 Projects using Kleros arbitration through address tag TCR 🔵 #### Etherscan Etherscan uses and displays the address tags from the Kleros decentralized address tag registries on [Ethereum Mainnet](https://curate.kleros.io/tcr/0x6e31d83b0c696f7d57241d3dffd0f2b628d14c67?chainId=1) and the [xDai/Gnosis Chain](https://curate.kleros.io/tcr/0x76944a2678A0954A610096Ee78E8CEB8d46d5922?chainId=100)). These tags are contributed and verified by the community, and their usage in Etherscan greatly increases the security for Web3 users by allowing them to transact with more confidence with the contracts they are interacting with. ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fe38CENBW6k1oePqh4H1Q%2Fimage.png?alt=media\&token=84fb49ab-bcf1-4ce2-b80f-f9d3e5868b7e) ### 👤 Projects using Kleros arbitration through Proof of Humanity👤 #### Gitcoin Grants Gitcoin Grants is a product enabling the funding of public goods using quadratic funding. It uses the Proof of Humanity registry as a Sybil Resistance tool. It gives a "Trust Bonus" to its users registered as humans which will increase the amount matched for their donations. ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-b9acbb5e8b2a602413b0e3b0a44acc50a8cfae85%2FPoH-Gitcoin.gif?alt=media) #### Ripio Credit Network [RCN](https://ripiocredit.network) is an open-source global credit network that connects lenders, borrowers, and loan originators on the blockchain to create frictionless, transparent, and borderless debt markets. It uses the Proof of Humanity registry to certify that borrowers/lenders are humans and improve trust. #### Universal Basic Income token (UBI) [UBI](https://blog.kleros.io/introducing-ubi-universal-basic-income-for-humans/) is a token built on top of the Proof of Humanity registry that is streamed directly to an Ethereum address as long as it gets verified as a human in the Proof of Humanity registry and starts the accrual process, establishing a fair and ongoing distribution model. It provides universal access to liquidity that serves to inhibit financial coercion of public decisions and is tradable in all open markets {% hint style="info" %} Check out the full Kleros Ecosystem page [**here**](https://www.notion.so/kleros/Kleros-ecosystem-f013376368364a5ebc0bbee176ed7eb1), showing all 60+ of our partners and collaborators. {% endhint %} # Kleros Analytics Community-led resources enabling the data analysis of Kleros smart contracts ## Explorers * [Kleros Board](http://klerosboard.com/): Exhaustive Kleros Court Explorer made by the community * [Kleros DB](https://klerosdb.eth.link/): Graph protocol-based Case and Court Explorer made by the community ## Data * Simple Kleros dashboard on [Dune Analytics](https://duneanalytics.com/tianqi/kleros-a-decentralized-disputes-resolution-protocal) ### Case Search Engine * [Kleros case search engine](https://vagarish.forer.es/) parsing through evidence (test and PDF) # Scalability & Cross-chain How Kleros Courts can scale and communicate with blockchains other than Ethereum ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-4e0e358f6ec556daf3c70ad9fb63ce0f92e5409b%2FScalability%20Roadmap%20\(2\).png?alt=media) ## **⚖️ THE ROAD TO KLEROS SCALABILITY ⚖️** Let us navigate together the few steps the Kleros Court will go through to transition from being the go-to Ethereum arbitration protocol to becoming a fully-fledged, scalable, and interoperable Justice system for the crypto world. * **CURRENT SITUATION**\ Kleros Court is deployed on Ethereum mainnet and mainly rules on disputes for Dapps hosted on the same blockchain (except for the bridge/proxy system for xDai Omen arbitration). Disputes are medium to high-value cases fit for Ethereum limited bandwidth.
* **MAY-JUNE 2021**\ A dedicated “xDai Kleros Court” is deployed on the xDAI chain to enable data curation and other small to medium value use cases to benefit from Kleros arbitration services. \\ * **EARLY Q3 2021**\ As more and more xDai Dapps uses Kleros dispute resolutions, cases can be appealed until they are ruled on the main Kleros Court on mainnet, improving security. The same system can be deployed to other side chains / commit chains such as Polygon.\\ * **Q3/Q4 2021**\ Kleros Court V2 and its new features (to be revealed soon) are deployed on a ZK or Optimistic rollup (we are still testing both layer 2 solutions). It can natively rule on disputes on the same rollup while bridges and proxies to other chains / L2s are developed.\\ * **2022**\ Kleros Court V2 on a rollup becomes the main hub for all disputes and the secure backstop for all cases. Dapps and Defi products on ETH1, all sidechains, other rollups and EVM chains are safely transported to Kleros Court V2 through proxy contracts.\\ **Kleros becomes the scalable dispute resolution protocol for the multi-chain ecosystem.**\\ 🔎 [Our latest thoughts and investigations about Kleros Scalability](https://blog.kleros.io/ethereum-scalability-and-kleros/) 🔎 {% content-ref url="/pages/-MQqpc3Om6H7-etTeQKx" %} [Using Kleros arbitration for Dapps on xDai/Gnosis](/integrations/scalability-and-crosschain/xdai) {% endcontent-ref %} # Using Kleros arbitration for Dapps on xDai/Gnosis In the future v2 version of our court, disputes on the xDai/Gnosis chain will be passed over the bridge to our main court for arbitration in the rollup environment of choice. ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-12f9ab6ee8f593519d587763f1ea7a7b45ee761b%2FKleros_Reality.eth_Arbitration_for_Omen_on_xDai.png?alt=media) # Integrations FAQ Frequently Asked Questions by Projects integrating with Kleros ## **If I integrate with Kleros, do I need to ask my users to hold some PNK?** Your product users do not need to interact with PNK at all. Kleros token is completely absent from your user flows and abstracted from your product interface. PNK is only needed for jurors to be drawn for jury duty and provide the dispute resolution as a service for your application. ***A useful analogy**:* If your DeFi project gets its price data from Chainlink oracles, it does not mean that your users need to own LINK. The LINK token powers the service provided by the oracle middleware. Your users never see it. It is the same for PNK. ## **Can I replace Kleros with a community vote or arbitration contract comprised only of my governance token holders?** It may be tempting to give additional utility to your project's native governance token by having it also handle the dispute resolution through voting, but it presents several weaknesses and risks: ***Rebuilding a weaker single-use court system :*** If a Dapp recreates a system where a few randomly selected token holders vote, then they will basically have to recreate a version of a dedicated arbitration system such as Kleros Courts - except that if it is the only utility of their token, then it won't benefit from network effects that Kleros has, where combining a lot of use cases together gives the token enough value to resist 51% attacks. Moreover, If they tack Kleros-like features onto a token that does something else/has value for some other reason, they will not have any guarantee that the culture around their token will develop appropriately so that people reliably stake so that their court can have good resistance to those same 51% attacks. ***Community-wide Vote Fatigue:*** If a project uses its native governance token to have every token holder vote on every dispute ever raised, it will require a massive duplication of effort and might be plagued by low response rates progressively creating security issues in the form of claim validation vote that could easily be swayed by a single whale. ***Biased Jury:*** If a governance token "whale" gets into a dispute on your product and that arbitration goes through a vote with the same governance token, then this whale will be incentivized to vote with no regard to the truth and to unfairly tip the scale in its favor. ## How much does using Kleros cost? Kleros Courts are currently only deployed on Ethereum mainnet. ***Gas fees:*** As for any smart contract, interacting with Kleros means paying gas fees when sending a transaction. The gas price will vary 24/7 depending on the current utilization of the whole Ethereum blockchain and thus, the gas fee will also vary with it. ***Arbitration fees:*** This is a product of the number of jurors you choose to draw into the dispute and the juror fee applicable to the (sub)court of choice (juror fees are fixed per court). We can't use anonymous jurors in my use case. Can we tweak Kleros to only select jurors from a pre-vetted pool? At this point, it is not possible to select jurors from a pre-defined pool. Anyone having tokens can self-select to be drawn randomly as a juror. ## Can/should I prevent new evidence from being submitted after a dispute has been initiated? It is not possible to stop this from a technical perspective, and it should not be done either as it could lead to the censorship of one of the disputing sides. What can be done is to mention that certain important evidences of a dispute must be submitted at the start of dispute, otherwise the jury must reject the claim. ## Which project is currently using Kleros and how has it worked for them? We invite you to take a look at our [Live Integrations](https://kleros.gitbook.io/docs/integrations/live-and-upcoming-integrations) page for the answer. # Arbitration Development Contract standards for arbitration and evidence ## Getting Started The following sections detail the smart contract standards used in creating applications that leverage the Kleros Court to adjudicate disputes. Take our quick DoDAO crash course on arbitration development and earn this NFT for your on-chain credential collection -

On-chain credentials are the future!

{% content-ref url="/pages/-MQq2F9KT7vK9u2aUzqn" %} [ERC-792: Arbitration Standard](/developer/arbitration-development/erc-792-arbitration-standard) {% endcontent-ref %} {% content-ref url="/pages/-MQqCKRo6urkDsq1Ctnv" %} [ERC 1497: Evidence Standard](/developer/arbitration-development/erc-1497-evidence-standard) {% endcontent-ref %} # ERC-792: Arbitration Standard A standard for Arbitrable and Arbitrator contracts ### Abstract The ERC-792 - Arbitration Standard describes a standard of `Arbitrable` and `Arbitrator` contracts. Every Arbitrable contract can be adjudicated by every Arbitrator contract. Arbitrator contracts give rulings and Arbitrable contracts enforce them. ### Motivation Using two contracts allows separation between the ruling and its enforcement. This abstraction allows `Arbitrable` contract developers not to have to know the internal process of the `Arbitrator` contracts. Neither do `Arbitrator` contract developers with `Arbitrable` ones.\ It allows dapps to easily switch from one arbitration service to another one. Or to allow their users to choose themselves their arbitration services. ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-3ddb1cbe54237ded82a5bce1f8bb0b896b66ee89%2Fimage.png?alt=media) ### Arbitrable Interface ```solidity // SPDX-License-Identifier: MIT pragma solidity ^0.8.0; import "./IArbitrator.sol"; /** * @title IArbitrable * Arbitrable interface. * When developing arbitrable contracts, we need to: * - Define the action taken when a ruling is received by the contract. * - Allow dispute creation. For this a function must call arbitrator.createDispute{value: _fee}(_choices,_extraData); */ interface IArbitrable { /** * @dev To be raised when a ruling is given. * @param _arbitrator The arbitrator giving the ruling. * @param _disputeID ID of the dispute in the Arbitrator contract. * @param _ruling The ruling which was given. */ event Ruling(IArbitrator indexed _arbitrator, uint256 indexed _disputeID, uint256 _ruling); /** * @dev Give a ruling for a dispute. Must be called by the arbitrator. * The purpose of this function is to ensure that the address calling it has the right to rule on the contract. * @param _disputeID ID of the dispute in the Arbitrator contract. * @param _ruling Ruling given by the arbitrator. Note that 0 is reserved for "Not able/wanting to make a decision". */ function rule(uint256 _disputeID, uint256 _ruling) external; } ``` ### Arbitrator Interface ```solidity // SPDX-License-Identifier: MIT pragma solidity ^0.8.0; import "./IArbitrable.sol"; /** * @title Arbitrator * Arbitrator abstract contract. * When developing arbitrator contracts we need to: * - Define the functions for dispute creation (createDispute) and appeal (appeal). Don't forget to store the arbitrated contract and the disputeID (which should be unique, may nbDisputes). * - Define the functions for cost display (arbitrationCost and appealCost). * - Allow giving rulings. For this a function must call arbitrable.rule(disputeID, ruling). */ interface IArbitrator { enum DisputeStatus { Waiting, Appealable, Solved } /** * @dev To be emitted when a dispute is created. * @param _disputeID ID of the dispute. * @param _arbitrable The contract which created the dispute. */ event DisputeCreation(uint256 indexed _disputeID, IArbitrable indexed _arbitrable); /** * @dev To be emitted when a dispute can be appealed. * @param _disputeID ID of the dispute. * @param _arbitrable The contract which created the dispute. */ event AppealPossible(uint256 indexed _disputeID, IArbitrable indexed _arbitrable); /** * @dev To be emitted when the current ruling is appealed. * @param _disputeID ID of the dispute. * @param _arbitrable The contract which created the dispute. */ event AppealDecision(uint256 indexed _disputeID, IArbitrable indexed _arbitrable); /** * @dev Create a dispute. Must be called by the arbitrable contract. * Must be paid at least arbitrationCost(_extraData). * @param _choices Amount of choices the arbitrator can make in this dispute. * @param _extraData Can be used to give additional info on the dispute to be created. * @return disputeID ID of the dispute created. */ function createDispute(uint256 _choices, bytes calldata _extraData) external payable returns (uint256 disputeID); /** * @dev Compute the cost of arbitration. It is recommended not to increase it often, as it can be highly time and gas consuming for the arbitrated contracts to cope with fee augmentation. * @param _extraData Can be used to give additional info on the dispute to be created. * @return cost Amount to be paid. */ function arbitrationCost(bytes calldata _extraData) external view returns (uint256 cost); /** * @dev Appeal a ruling. Note that it has to be called before the arbitrator contract calls rule. * @param _disputeID ID of the dispute to be appealed. * @param _extraData Can be used to give extra info on the appeal. */ function appeal(uint256 _disputeID, bytes calldata _extraData) external payable; /** * @dev Compute the cost of appeal. It is recommended not to increase it often, as it can be highly time and gas consuming for the arbitrated contracts to cope with fee augmentation. * @param _disputeID ID of the dispute to be appealed. * @param _extraData Can be used to give additional info on the dispute to be created. * @return cost Amount to be paid. */ function appealCost(uint256 _disputeID, bytes calldata _extraData) external view returns (uint256 cost); /** * @dev Compute the start and end of the dispute's current or next appeal period, if possible. If not known or appeal is impossible: should return (0, 0). * @param _disputeID ID of the dispute. * @return start The start of the period. * @return end The end of the period. */ function appealPeriod(uint256 _disputeID) external view returns (uint256 start, uint256 end); /** * @dev Return the status of a dispute. * @param _disputeID ID of the dispute to rule. * @return status The status of the dispute. */ function disputeStatus(uint256 _disputeID) external view returns (DisputeStatus status); /** * @dev Return the current ruling of a dispute. This is useful for parties to know if they should appeal. * @param _disputeID ID of the dispute. * @return ruling The ruling which has been given or the one which will be given if there is no appeal. */ function currentRuling(uint256 _disputeID) external view returns (uint256 ruling); } ``` {% hint style="info" %} The `extraData` is a byte array that is used to provide additional information about a dispute in a smart contract system. It consists of 64 bytes in total. The byte array is divided into two parts: 1. ID of the subcourt (32 bytes): The first 32 bytes of the `extraData` array are dedicated to storing the ID of the subcourt where the dispute will be created. The subcourt ID is represented by a `uint96` data type. Subcourt IDs can be found on [this page](https://klerosboard.com/1/courts). 2. Minimum number of jurors required (32 bytes): The next 32 bytes of the `extraData` array are reserved for specifying the minimum number of jurors that are required for the dispute. This value is represented by a `uint` data type. The minimum number required for most disputes is usually 3. By passing the `extraData` array to a relevant function (such as the `arbitrationCost` and `createDispute` functions), the subcourt ID and the minimum number of jurors can be extracted and utilized for further operations within the Arbitrator's smart contract. {% endhint %} In the linked documentation, you will be guided through the usage of this standard. We will implement some examples for `Arbitrable` and `Arbitrator` contracts. 📖 [Link to full ERC-792 documentation](https://developer.kleros.io/en/latest/index.html) 📖 📜 [EIP-792](https://github.com/ethereum/EIPs/issues/792) 📜 # ERC 1497: Evidence Standard An evidence standard for arbitration 📖 [Link to full ERC-1497 documentation](https://developer.kleros.io/en/latest/erc-1497.html) 📖‌ 📜 [EIP-1497](https://github.com/ethereum/EIPs/issues/1497) 📜 ### Abstract The following describes the standards for `MetaEvidence` and `Evidence` for dispute resolution. `Evidence` is provided by a participant in a dispute in order to support their assertion. `MetaEvidence` gives context to the dispute so that arbitrators are able to accurately and fairly evaluate it. This standard follows [ERC 792](https://github.com/ethereum/EIPs/issues/792) and references `Arbitrator` and `Arbitrable` contracts. ### Motivation Standardizing `MetaEvidence` and `Evidence` allows interoperability between `Arbitrable` DApps (DApps where disputes can arise) and `Arbitrator` DApps (DApps which can be used to resolve disputes). It allows these applications to easily switch from one arbitration service to another, or to let their users decide which arbitration service to use without having to spend time to integrate with all of them. `MetaEvidence` is required to provide the context of the dispute. `Evidence` allows for dispute participants to submit extra information for the arbitrators. The ERC792 standardizes the way the smart contracts interact with each other while this standard is made to standardize the way the interfaces interact in the context of disputes. ![](https://3167298399-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LPbPWuMtwBOvW0iuxyw%2Fuploads%2Fgit-blob-6ad9498efd07d5375b73728d30f2fde5419aa893%2Fimage%20\(7\)%20\(2\)%20\(2\)%20\(2\)%20\(2\)%20\(2\)%20\(2\).png?alt=media) ### Evidence Interface ```solidity // SPDX-License-Identifier: MIT pragma solidity ^0.8.0; import "../IArbitrator.sol"; /** @title IEvidence * ERC-1497: Evidence Standard */ interface IEvidence { /** * @dev To be emitted when meta-evidence is submitted. * @param _metaEvidenceID Unique identifier of meta-evidence. * @param _evidence IPFS path to metaevidence, example: '/ipfs/QmbsNh1pDfqKmaySamNCnEoWQpd8E7RfpBrF3HPZS7xKVK' */ event MetaEvidence(uint256 indexed _metaEvidenceID, string _evidence); /** * @dev To be raised when evidence is submitted. Should point to the resource (evidences are not to be stored on chain due to gas considerations). * @param _arbitrator The arbitrator of the contract. * @param _evidenceGroupID Unique identifier of the evidence group the evidence belongs to. * @param _party The address of the party submiting the evidence. Note that 0x0 refers to evidence not submitted by any party. * @param _evidence IPFS path to evidence, example: '/ipfs/Qmarwkf7C9RuzDEJNnarT3WZ7kem5bk8DZAzx78acJjMFH/evidence.json' */ event Evidence( IArbitrator indexed _arbitrator, uint256 indexed _evidenceGroupID, address indexed _party, string _evidence ); /** * @dev To be emitted when a dispute is created to link the correct meta-evidence to the disputeID. * @param _arbitrator The arbitrator of the contract. * @param _disputeID ID of the dispute in the Arbitrator contract. * @param _metaEvidenceID Unique identifier of meta-evidence. * @param _evidenceGroupID Unique identifier of the evidence group that is linked to this dispute. */ event Dispute( IArbitrator indexed _arbitrator, uint256 indexed _disputeID, uint256 _metaEvidenceID, uint256 _evidenceGroupID ); } ``` ## Introduction to the Evidence Standard The purpose of this specification is to create a standard way for DApps that are part of the dispute resolution process to share context and information. This standard should allow DApps that have disputes they need arbitrated a way to provide the details of the dispute to the Arbitrator. Conversely, for an Arbitrator interface to be able to display a dispute to be ruled on, there needs to be a standard way for the interface to fetch evidence from the Arbitrable contracts. \ Let’s consider an example where a developer is asked to develop an e-commerce website. The contracting party locks up the payment for the website in an escrow smart contract. Unfortunately, once the developer submits her work, there is a disagreement on whether the terms have been met and a dispute is raised in the smart contract. Now the case will go to an arbitration service, but in order for the arbitrators to make a fair ruling, they need to understand what the dispute is about and to take into consideration the arguments from both parties. In essence, there are two kinds of evidence needed for the arbitrators to be able to make a ruling. The first type of evidence, called MetaEvidence, provides the whole picture behind the dispute. In this case, it could be the original off-chain contract or agreement, as well as important information regarding what consequence(s) an arbitrator's ruling will have. MetaEvidence is used to convey this information to the chosen arbitrator. The second type is the material evidence, such as emails, screenshots and contracts or testimony provided by each party to try to prove that the dispute should be ruled in their favor. In the above case, the programmer might submit the code as evidence, while the contracting party submits screenshots of what is missing. In the case of our Evidence Standard, MetaEvidence is the context while Evidence is the proof provided by each party. ## How it works \ In order to provide flexibility for all different types of disputes, and to try to keep minimal information on the chain, we decided to create standardized JSON objects that can be hosted anywhere and fetched by an interface to display a dispute. Below we provide some examples. For more information on what each field does, take a look at the [standard specification](https://github.com/ethereum/EIPs/issues/1497). ### MetaEvidence: We have already discussed what MetaEvidence is, so let’s take a look at how a piece of MetaEvidence might actually look and how it would be used. Each dispute has one piece of MetaEvidence that is used to give all of the contextual information for a contract that might be disputed. MetaEvidence should be created at the same time as the agreement so that it can be impartial. The only restriction on MetaEvidence is that it must be created before a dispute can be raised in the smart contract. The fields in this MetaEvidence JSON are as follows: * `category`: The category that the dispute belongs to. All values are accepted here, but it's good to align it with other past disputes of the same kind for consistency. * `title`: A title to describe what the dispute is about. Can be constant for all disputes from your dApp. * `description`: Text to describe the situation of the case. It can also be static for all cases, in which you will just have a generic description that describes what to look out for in these cases. * `question`: This is question posed to the jury after they review all the facts, documents and evidences of the case. * `rulingOptions`: * type: Can be one of the following values: * `single-select`: the jurors select one answer among the provided options. * `multiple-select`: the jurors can select any number of the provided options. * `uint`: the jurors input an unsigned integer. * `int`: the jurors input a signed integer. * `string`: the jurors enter a string. String must fit into `bytes32`. * `precision`: only applicable for ruling types `int` and `uint` to indicate the number of decimal places a ruling contains. * `titles`: an array of the options available to the jurors. NOTE: the sequence of the titles is important as they map directly to the rulings you get when the Arbitrator responds to your Arbitrable using the `rule()` function. * `descriptions`: the description of the `rulingOption` titles. * `fileURI`: The URI points to the primary document of the case, which is the foundational document that establishes the rules for the dispute. This document is typically a dispute policy that defines criteria for resolution and serves as the basis for jurors to make their decisions. We have established dispute policies for the following products that can be referenced: * **Kleros Scout** * [ATR (Address Tag Registry)](https://ipfs.kleros.io/ipfs/QmXuUER9is6n4XgiDtNnZBqPCTsJvMj1ku5gQg5EZGxfxw/atr-registry-policy.pdf) * [CDN (Curated Domain Names)](https://ipfs.kleros.io/ipfs/QmVL3hR8E2XcnJ1PjKARqh7e5SDJM1HeKLsUYnLnUyKEWo/domain-name-dispute-resolution-policy-v1.0.pdf) * [Snap](https://ipfs.kleros.io/ipfs/QmcARXVNcX8LpvjMZDgL8AQyW8q1XxwMfVTPSJ3YRvCpvx/snap-dispute-policy.pdf) * **Oracle** * [Oracle Dispute Policy](https://ipfs.kleros.io/ipfs/QmfHRnNnBxxa1uD5MKP2HNrB8hWjHsrNfqaLetiEa8LfaT/reality-eth-dispute-policy.pdf) * **Court** * [Court Policies](https://ipfs.kleros.io/ipfs/QmZYxRxwKMPpSMq8MJSd5QFeSUZoii7hFwXJvQn7bvnbCq/kleros-court-justice-policy.pdf) * **Governor** * [Governor Policy](https://ipfs.kleros.io/ipfs/QmVMqK7yXTXVXzLGJgT1XLJeaWD5LJhN2A2PrqMM41BbWY/kleros-governor-policy.pdf) * **Proof of Humanity** * [PoH v2 Policy](https://ipfs.kleros.io/ipfs/QmNSV9xXKiBtaRW1MYmFaVkqsD1Qez2ZDX1jyP21j87jxj/poh-v2-policy.pdf) For guidance on creating your own dispute policy document, please refer to our [Policy Writing Guide](https://docs.kleros.io/integrations/policy-writing-guide). * `evidenceDisplayInterfaceURI`: This field provides a URI that points to a display interface for rendering evidence in a more user-friendly way for arbitrators. **Core purpose:** * Creates a custom UI for presenting evidence within the arbitration interface * Allows for branded, styled presentation of dispute evidence * Renders in an iframe within the arbitrator's interface **The query parameters passed to it include:** * `disputeID`: Identifier for the specific dispute * `chainID`: The blockchain network ID * `arbitratorContractAddress`: Address of the arbitrator contract * `arbitratorJsonRpcUrl`: JSON-RPC endpoint for the arbitrator's blockchain * `arbitratorChainID`: Chain ID for the arbitrator * `arbitrableContractAddress`: Address of the arbitrable contract * `arbitrableChainID`: Chain ID for the arbitrable contract * `arbitrableJsonRpcUrl`: JSON-RPC endpoint for the arbitrable contract's blockchain * `jsonRpcUrl`: General JSON-RPC URL for the arbitrator's environment (typically Ethereum mainnet or Gnosis Chain) While there are no hard limits to the amount of content that can be displayed, it's recommended to keep the interface under 360px in height to ensure it's easily readable within the court interface. **When to use it:** 1. **Complex Financial Transactions**: For payment histories, multi-party transactions, or time-series data that benefits from visualization. 2. **Evidence Context and Relationships**: Standard evidence attachments are recommended for both textual and non-textual evidence, but the display interface can organize these attachments, provide context, and visualize relationships between different evidence elements. 3. **Branded Experience**: When maintaining your application's visual identity throughout the dispute resolution process is important. \ **Examples:** [escrow](https://github.com/kleros/escrow-evidence-display), [reality same chain](https://github.com/kleros/realitio-interface), [reality cross-chain](https://github.com/kleros/cross-chain-realitio-proxy/tree/master/evidence-display), [curate](https://github.com/kleros/gtcr-injected-uis) * `dynamicScriptURI`: This field provides a URI to a script that can dynamically update the MetaEvidence when it's fetched by an arbitrator interface. This script must expose a function called `getMetaEvidence` that returns JSON data, which is then merged with the original MetaEvidence JSON. **Core purpose:** * Makes MetaEvidence more dynamic without requiring on-chain updates * Reduces gas costs by avoiding repeated on-chain MetaEvidence updates * Provides flexibility for disputes with changing content or context **When to use it:** 1. **Template-Based Disputes**: For similar disputes with different parameters. 2. **Gas Optimization**: When emitting new MetaEvidence events for each dispute would be prohibitively expensive. 3. **Dynamic Content**: When dispute details aren't fully known at contract creation time but follow a predictable pattern.\ **Examples:** [reality same chain](https://github.com/kleros/realitio-script), [reality cross-chain](https://github.com/kleros/cross-chain-realitio-proxy/tree/master/dynamic-script) | If you need to | Consider using | | --------------------------------------- | --------------------------- | | Visualize transaction flows | evidenceDisplayInterfaceURI | | Show relationships between evidence | evidenceDisplayInterfaceURI | | Maintain brand identity in disputes | evidenceDisplayInterfaceURI | | Handle many similar disputes | dynamicScriptURI | | Reduce gas costs for many disputes | dynamicScriptURI | | Adapt MetaEvidence at runtime | dynamicScriptURI | | Complex visualization + dynamic content | Both fields together | **Using Both Fields Together** When your dispute resolution needs are complex, you can use both fields together in the same MetaEvidence. This allows you to have both dynamic content and custom visualization. Here's an example of a MetaEvidence JSON: ```json { "category": "Insurance", "title": "Unslashed insurance claim", "description": "The claimant requested a compensation for damages covered by Unslashed insurance in the provided amount.", "question": "Should their claim be paid out?", "rulingOptions": { "type": "single-select", "titles": [ "Accept the claim", "Reject the claim" ], "descriptions": [ "Accept the claim if the claimant 1) incurred the alleged damages, 2) is covered by a relevant policy, 3) the damages and their cover are at least the claimed amount at the moment when the claim was filled.", "Reject the claim if any of the acceptance criteria do not hold." ] }, "fileURI": "/ipfs/QmeTBY7jZe2ut5WjifNASADo3E4zBxkMd62WwBpXtwP9pg", "evidenceDisplayInterfaceURI": "https://app.unslashed.finance/embed/claims" } ``` Below you will find a diagram that shows how the elements in the MetaEvidence JSON get displayed on the [Court](https://court.kleros.io/cases/1213) and [Dispute Resolver](https://resolve.kleros.io/cases/1213) interfaces.

A screenshot of Case #1213 on resolve.kleros.io, showcasing all the important elements in the MetaEvidence JSON of this case.

Here is an example of the URL with query string used by the iframe on the Arbitrator interface: ```typescript // URL decoded example for readability https://cdn.kleros.link/ipfs/QmSL8d82dMhcThwERWaF4LtmCa4hgV7TyPjAo4fKCzPVkv/index.html?{"disputeID":"1500","chainID":1,"arbitratorContractAddress":"0x988b3a538b618c7a603e1c11ab82cd16dbe28069","arbitratorJsonRpcUrl":"https://rpc.eth.gateway.fm","arbitratorChainID":1,"arbitrableContractAddress":"0xC5E9dDebb09Cd64DfaCab4011A0D5cEDaf7c9BDb","arbitrableChainID":1,"arbitrableJsonRpcUrl":"https://rpc.eth.gateway.fm","jsonRpcUrl":"https://rpc.eth.gateway.fm"} ``` {% hint style="info" %} Pro-tip: To avoid having to create a new MetaEvidence JSON and pin it to IPFS prior to every dispute, you can use just a static MetaEvidence JSON, and use a `evidenceDisplayInterfaceURI` that dynamically displays different information based on the query string. {% endhint %} ### Evidence: It is also essential in many types of disputes that the participants have a chance to show their viewpoint and give reasons why they believe they are right. Therefore there needs to be a way for an Arbitrator to receive Evidence. The Evidence JSON file includes the following properties: ```json { "fileURI": "/ipfs/QmWQV5ZFFhEJiW8Lm7ay2zLxC2XS4wx1b2W7FfdrLMyQQc", "fileHash": "QmWQV5ZFFhEJiW8Lm7ay2zLxC2XS4wx1b2W7FfdrLMyQQc", "fileTypeExtension": "pdf", "name": "Email clarifying the terms of the contract.", "description": "This is an email sent to Alice from Bob that clarifies that the recommendation page that was expected", "selfHash": "QmUQMJbfiQYX7k6SWt8xMpR7g4vwtAYY1BTeJ8UY8JWRs9" } ``` #### How to use these JSON files: So now we have JSON files with our two types of evidence but we still need a way to link them to our smart contract so that our DApps can interact seamlessly. MetaEvidence and Evidence are submitted and looked up via smart contract event logs. The standard specifies some new events for your smart contracts. When an Evidence is submitted, an event is raised that includes a URI to the JSON file that the submitter can host anywhere they choose. This way we can leverage the immutability and availability of the blockchain to create a permanent log of submission that any interface can look up and use to access the Evidence JSON.\\ #### Keeping the data safe with hashes: In contentious disputes, it is crucial that Arbitrators can be sure that they receive accurate Evidence and MetaEvidence. For example, if MetaEvidence is tampered with, one of the participants can switch the labels on the ruling options, and an Arbitrator might send funds to the wrong party thinking they are voting the opposite way. To protect against Evidence or MetaEvidence being modified, a series of hashes are used. The JSON for both MetaEvidence and Evidence contains hash fields for things such as linked files. The standard also allows for the hash to be used as the name of the file, like the format IPFS uses, so that files hosted on distributed platforms that guarantee data integrity don’t require any extra work. The arbitrators can use these hashes that are provided when Evidence or MetaEvidence is submitted to verify that nothing has been changed. # Arbitrable Proxy A simpler way to build arbitrable applications. The arbitrable proxy contract abstracts away most of the heavy lifting associated with implementing the ERC792 and ERC1497 standards from scratch in an arbitrable application. It abstracts away the evidence and appeal management logic from your contact, requiring you to handle just the dispute creation and ruling retrieval logic. ## Getting Started ### Step 1: Import the IArbitrableProxy interface into your project ```solidity // SPDX-License-Identifier: MIT pragma solidity ^0.8.0; import "@kleros/erc-792/contracts/IArbitrator.sol"; /** * @title IArbitrableProxy * A general purpose arbitrable contract. Supports non-binary rulings. */ interface IArbitrableProxy { function arbitrator() external view returns (IArbitrator arbitrator); function createDispute( bytes calldata _arbitratorExtraData, string calldata _metaevidenceURI, uint256 _numberOfRulingOptions ) external payable returns (uint256 disputeID); struct DisputeStruct { bytes arbitratorExtraData; bool isRuled; uint256 ruling; uint256 disputeIDOnArbitratorSide; } function externalIDtoLocalID( uint256 _externalID ) external returns (uint256 localID); function disputes( uint256 _localID ) external returns ( bytes memory extraData, bool isRuled, uint256 ruling, uint256 disputeIDOnArbitratorSide ); function submitEvidence(uint256 _localDisputeID, string calldata _evidenceURI) external; } ``` #### Usage ```solidity contract MyArbitrable { IArbitrableProxy arbitrableProxy = IArbitrableProxy(); } ``` ### Step 2: Create disputes through the proxy and paying the arbitration cost through the same transaction. {% hint style="info" %} The arbitration cost paid when calling the `createDispute()` function of the arbitrableProxy is the same as that of calling the same function on the final arbitrator (i.e. Kleros Court). The cost estimation is therefore best done by directly polling it from the final arbitrator (i.e. the [`arbitrationCost()` function of Kleros Liquid](https://etherscan.deth.net/address/0x988b3a538b618c7a603e1c11ab82cd16dbe28069#L1816)) {% endhint %} ```solidity contract MyArbitrable { IArbitrableProxy arbitrableProxy = IArbitrableProxy(); function foo( bytes calldata extraData, string memory evidenceURI, uint256 rulingOptions ) { uint256 disputeID = arbitrableProxy.createDispute{value: msg.value}( extraData, evidenceURI, rulingOptions ); // do something with disputeID } } ``` ### Step 3: Create a `fetchRuling` function. A key difference between using the proxy and implementing your own ERC792 arbitrable from scratch is that a rule function is not directly called in your contract by the arbitrator. The proxy stores the data of rulings locally in an array and its up to you to query the rulings relevant to your contract. Let's first take a look at how rulings are stored on the arbitrable proxy then move on to how to implement a fetchRuling function in your contract. ```solidity /// https://github.com/kleros/arbitrable-proxy-contracts/blob/master/contracts/ArbitrableProxy.sol contract ArbitrableProxy is IDisputeResolver { // ... // ... // ... struct DisputeStruct { bytes arbitratorExtraData; bool isRuled; uint256 ruling; uint256 disputeIDOnArbitratorSide; } DisputeStruct[] public disputes; function rule(uint256 _externalDisputeID, uint256 _ruling) external override { uint256 localDisputeID = externalIDtoLocalID[_externalDisputeID]; DisputeStruct storage dispute = disputes[localDisputeID]; require(msg.sender == address(arbitrator), "Only the arbitrator can execute this."); require(_ruling <= numberOfRulingOptions[localDisputeID], "Invalid ruling."); require(dispute.isRuled == false, "This dispute has been ruled already."); dispute.isRuled = true; dispute.ruling = _ruling; Round[] storage rounds = disputeIDtoRoundArray[localDisputeID]; Round storage lastRound = disputeIDtoRoundArray[localDisputeID][rounds.length - 1]; // If only one ruling option is funded, it wins by default. Note that if any other ruling had funded, an appeal would have been created. if (lastRound.fundedRulings.length == 1) { dispute.ruling = lastRound.fundedRulings[0]; } emit Ruling(IArbitrator(msg.sender), _externalDisputeID, dispute.ruling); } } ``` ```solidity contract MyArbitrable { IArbitrableProxy arbitrableProxy = IArbitrableProxy(); function foo( bytes calldata extraData, string memory evidenceURI, uint256 rulingOptions ) { uint256 disputeID = arbitrableProxy.createDispute{value: msg.value}( extraData, evidenceURI, rulingOptions ); // do something with disputeID } function fetchRuling(uint256 disputeID) { (, bool isRuled, uint256 ruling) = arbitrableProxy.disputes(disputeID) // do something with ruling if isRuled } } ``` And that's it! With this, you would have a fully trustless integration with Kleros Court for less than half the work of a fully ERC792 compliant integration. # Arbitration by Example ERC-792 & ERC-1497 Implementation We've compiled a few examples of arbitrable smart contracts to demonstrate the standards discussed in [Arbitration Development](/developer/arbitration-development). Check out the full repository of Kleros interactions here: {% content-ref url="/pages/t9NRIu7vlvYVhRULVkHK" %} [ArbitrableDeposit.sol](/developer/arbitration-by-example/arbitrabledeposit.sol) {% endcontent-ref %} {% content-ref url="/pages/IvitL9RvPip9455Xzpce" %} [TwoPartyArbitrable.sol](/developer/arbitration-by-example/twopartyarbitrable.sol) {% endcontent-ref %} {% content-ref url="/pages/bOelhjApcLonSwMqF1pb" %} [Rental.sol](/developer/arbitration-by-example/rental.sol) {% endcontent-ref %} {% content-ref url="/pages/5TFf5Lmin4Oe43kOOl5I" %} [ArbitrableTransaction.sol](/developer/arbitration-by-example/arbitrabletransaction.sol) {% endcontent-ref %} {% content-ref url="/pages/EcjPeMDICeR5F8SzVHvt" %} [MultipleArbitrableTransaction.sol](/developer/arbitration-by-example/multiplearbitrabletransaction.sol) {% endcontent-ref %} {% content-ref url="/pages/EJMFmkIdbfiao2t6nucl" %} [MultipleArbitrableTokenTransaction.sol](/developer/arbitration-by-example/multiplearbitrabletokentransaction.sol) {% endcontent-ref %} # ArbitrableDeposit.sol ```solidity pragma solidity ^0.4.15; import "./Arbitrable.sol"; /** @title Arbitrable Deposit * This is a a contract which allow for an owner deposit. Anyone besides the owner can seek arbitration/file a claim as a claimant. * To develop a contract inheriting from this one, you need to: * - Redefine RULING_OPTIONS to explain the consequences of the possible rulings. * - Redefine executeRuling while still calling super.executeRuling to implement the results of the arbitration. */ contract ArbitrableDeposit is Arbitrable { address public owner; address public claimant; uint public timeout; // Time in seconds a party can take before being considered unresponding and lose the dispute. uint public ownerFee; // Total fees paid by the owner. uint public claimantFee; // Total fees paid by the claimant. uint public lastInteraction; // Last interaction for the dispute procedure. uint public disputeID; uint public amount; // Total amount deposited by owner. uint public claimAmount; // Claim amount a claimant proposes. uint public claimRate; // Rate of a claim the claimant must deposit as an integer. uint internal claimResponseAmount; // Amount which the Owner responds to the claimant's asking claim. uint public claimDepositAmount; // Total amount a claimant must deposit. enum Status {NoDispute, WaitingOwner, WaitingClaimant, DisputeCreated, Resolved} Status public status; uint8 constant AMOUNT_OF_CHOICES = 2; uint8 constant OWNER_WINS = 1; uint8 constant CLAIMANT_WINS = 2; string constant RULING_OPTIONS = "Owner wins;Claimant wins"; // A plain English of what rulings do. Need to be redefined by the child class. modifier onlyOwner{require(msg.sender == address(owner), "Can only be called by the owner."); _;} modifier onlyNotOwner{require(msg.sender != address(owner), "Cannot be called by the owner."); _;} modifier onlyClaimant{require(msg.sender == address(claimant), "Can only be called by the claimant."); _;} enum Party {Owner, Claimant} /** @dev Indicate that a party has to pay a fee or would otherwise be considered as loosing. * @param _party The party who has to pay. */ event HasToPayFee(Party _party); /** @dev Constructor. Choose the arbitrator * @param _arbitrator The arbitrator of the contract. * @param _timeout Time after which a party automatically loose a dispute. * @param _arbitratorExtraData Extra data for the arbitrator. * @param _metaEvidence Link to the meta evidence. */ constructor( Arbitrator _arbitrator, uint _timeout, bytes _arbitratorExtraData, uint _claimRate, string _metaEvidence ) Arbitrable(_arbitrator, _arbitratorExtraData) public payable { timeout = _timeout; claimRate = _claimRate; status = Status.NoDispute; amount += msg.value; owner = msg.sender; address(this).transfer(amount); emit MetaEvidence(0, _metaEvidence); } /** @dev Owner deposit to contract. To be called when the owner makes a deposit. */ function deposit() public payable onlyOwner { amount += msg.value; address(this).transfer(msg.value); } /** @dev File a claim against owner. To be called when someone makes a claim. * @param _claimAmount The proposed claim amount by the claimant. */ function makeClaim(uint _claimAmount) public onlyNotOwner { require(_claimAmount <= amount, "Cannot claim more than what is deposited."); claimant = msg.sender; claimAmount = _claimAmount; claimDepositAmount = (_claimAmount * claimRate) / 100; address(this).transfer(claimDepositAmount); status = Status.WaitingOwner; } /** @dev Owner response to claimant. To be called when the owner initates a * a response. * @param _responseAmount The counter-offer amount the Owner proposes to a claimant. */ function claimResponse(uint _responseAmount) public onlyOwner { require(_responseAmount <= claimDepositAmount, "The response amount has to be less than the claim deposit amount."); claimResponseAmount = _responseAmount; if (_responseAmount == claimDepositAmount) { claimant.transfer(_responseAmount); claimAmount = 0; amount = 0; status = Status.Resolved; } else { payArbitrationFeeByOwner(); } } /** @dev Pay the arbitration fee to raise a dispute. To be called by the owner. UNTRUSTED. * Note that the arbitrator can have createDispute throw, which will make this function throw and therefore lead to a party being timed-out. * This is not a vulnerability as the arbitrator can rule in favor of one party anyway. */ function payArbitrationFeeByOwner() public payable onlyOwner{ uint arbitrationCost = arbitrator.arbitrationCost(arbitratorExtraData); ownerFee += msg.value; // Require that the total pay at least the arbitration cost. require(ownerFee == arbitrationCost, "Owner fee must equal arbitration cost."); require(status < Status.DisputeCreated, "A dispute has already been raised."); // Make sure a dispute has not been created yet. lastInteraction = now; if (claimantFee < arbitrationCost) { // The claimant still has to pay. // This can also happens if he has paid, but arbitrationCost has increased. status = Status.WaitingClaimant; emit HasToPayFee(Party.Claimant); } else { // The claimant has also paid the fee. We create the dispute raiseDispute(arbitrationCost); } } /** @dev Pay the arbitration fee to raise a dispute. To be called by the claimant. UNTRUSTED. * Note that this function mirror payArbitrationFeeByOwner. */ function payArbitrationFeeByClaimant() public payable onlyClaimant { uint arbitrationCost = arbitrator.arbitrationCost(arbitratorExtraData); claimantFee += msg.value; // Require that the total pay at least the arbitration cost. require(claimantFee == arbitrationCost, "Claimant fee must equal arbitration cost."); require(status < Status.DisputeCreated, "A dispute has already been raised."); // Make sure a dispute has not been created yet. lastInteraction = now; if (ownerFee < arbitrationCost) { // The owner still has to pay. This can also happens if he has paid, but arbitrationCost has increased. status = Status.WaitingOwner; emit HasToPayFee(Party.Claimant); } else { // The owner has also paid the fee. We create the dispute raiseDispute(arbitrationCost); } } /** @dev Create a dispute. UNTRUSTED. * @param _arbitrationCost Amount to pay the arbitrator. */ function raiseDispute(uint _arbitrationCost) internal { status = Status.DisputeCreated; disputeID = arbitrator.createDispute.value(_arbitrationCost)(AMOUNT_OF_CHOICES,arbitratorExtraData); emit Dispute(arbitrator, disputeID, 0, 0); } /** @dev Reimburse owner if claimant fails to pay the fee. */ function timeOutByOwner() public onlyOwner { require(status == Status.WaitingClaimant, "The contract is not waiting for the claimant."); require(now >= lastInteraction + timeout, "Not enough time has passed."); executeRuling(disputeID,OWNER_WINS); } /** @dev Pay claimant if owner fails to pay the fee. */ function timeOutByClaimant() public onlyClaimant { require(status == Status.WaitingOwner, "The contract is not waiting for the owner."); require(now >= lastInteraction + timeout, "Not enough time has passed."); executeRuling(disputeID, CLAIMANT_WINS); } /** @dev Execute a ruling of a dispute. Pays parties respective amounts based on ruling. * This needs to be extended by contract inheriting from it. * @param _disputeID ID of the dispute in the Arbitrator contract. * @param _ruling Ruling given by the arbitrator. 1 : Allow owner deposit. 2 : Pay claimant. */ function executeRuling(uint _disputeID, uint _ruling) internal { require(_disputeID == disputeID, "Wrong dispute ID."); require(_ruling <= AMOUNT_OF_CHOICES, "Invalid ruling."); if (_ruling == OWNER_WINS) { owner.transfer(amount + claimAmount); claimant.transfer(claimResponseAmount); } else if (_ruling == CLAIMANT_WINS) claimant.transfer(amount); amount = 0; } } ``` # TwoPartyArbitrable.sol ```solidity pragma solidity ^0.4.15; import "./Arbitrable.sol"; /** @title Two-Party Arbitrable * @dev A contract between two parties which can be arbitrated. Both parties has to pay for the arbitration fee. The winning party will get its fee refunded. * To develop a contract inheriting from this one, you need to: * - Redefine RULING_OPTIONS to explain the consequences of the possible rulings. * - Redefine executeRuling while still calling super.executeRuling to implement the results of the arbitration. */ contract TwoPartyArbitrable is Arbitrable { uint public timeout; // Time in second a party can take before being considered unresponding and lose the dispute. uint8 public amountOfChoices; address public partyA; address public partyB; uint public partyAFee; // Total fees paid by the partyA. uint public partyBFee; // Total fees paid by the partyB. uint public lastInteraction; // Last interaction for the dispute procedure. uint public disputeID; enum Status {NoDispute, WaitingPartyA, WaitingPartyB, DisputeCreated, Resolved} Status public status; uint8 constant PARTY_A_WINS = 1; uint8 constant PARTY_B_WINS = 2; string constant RULING_OPTIONS = "Party A wins;Party B wins"; // A plain English of what rulings do. Need to be redefined by the child class. modifier onlyPartyA{require(msg.sender == partyA, "Can only be called by party A."); _;} modifier onlyPartyB{require(msg.sender == partyB, "Can only be called by party B."); _;} modifier onlyParty{require(msg.sender == partyA || msg.sender == partyB, "Can only be called by party A or party B."); _;} enum Party {PartyA, PartyB} /** @dev Indicate that a party has to pay a fee or would otherwise be considered as loosing. * @param _party The party who has to pay. */ event HasToPayFee(Party _party); /** @dev Constructor. Choose the arbitrator. * @param _arbitrator The arbitrator of the contract. * @param _timeout Time after which a party automatically loose a dispute. * @param _partyB The recipient of the transaction. * @param _amountOfChoices The number of ruling options available. * @param _arbitratorExtraData Extra data for the arbitrator. * @param _metaEvidence Link to the meta-evidence. */ constructor( Arbitrator _arbitrator, uint _timeout, address _partyB, uint8 _amountOfChoices, bytes _arbitratorExtraData, string _metaEvidence ) Arbitrable(_arbitrator,_arbitratorExtraData) public { timeout = _timeout; partyA = msg.sender; partyB = _partyB; amountOfChoices = _amountOfChoices; emit MetaEvidence(0, _metaEvidence); } /** @dev Pay the arbitration fee to raise a dispute. To be called by the party A. UNTRUSTED. * Note that the arbitrator can have createDispute throw, which will make this function * throw and therefore lead to a party being timed-out. * This is not a vulnerability as the arbitrator can rule in favor of one party anyway. */ function payArbitrationFeeByPartyA() public payable onlyPartyA { uint arbitrationCost = arbitrator.arbitrationCost(arbitratorExtraData); partyAFee += msg.value; require( partyAFee >= arbitrationCost, "Not enough ETH to cover arbitration costs." ); // Require that the total pay at least the arbitration cost. require(status < Status.DisputeCreated, "Dispute has already been created."); // Make sure a dispute has not been created yet. lastInteraction = now; // The partyB still has to pay. This can also happens if he has paid, but arbitrationCost has increased. if (partyBFee < arbitrationCost) { status = Status.WaitingPartyB; emit HasToPayFee(Party.PartyB); } else { // The partyB has also paid the fee. We create the dispute raiseDispute(arbitrationCost); } } /** @dev Pay the arbitration fee to raise a dispute. To be called by the party B. UNTRUSTED. * Note that this function mirror payArbitrationFeeByPartyA. */ function payArbitrationFeeByPartyB() public payable onlyPartyB { uint arbitrationCost = arbitrator.arbitrationCost(arbitratorExtraData); partyBFee += msg.value; require( partyBFee >= arbitrationCost, "Not enough ETH to cover arbitration costs." ); // Require that the total pay at least the arbitration cost. require(status < Status.DisputeCreated, "Dispute has already been created."); // Make sure a dispute has not been created yet. lastInteraction = now; // The partyA still has to pay. This can also happens if he has paid, but arbitrationCost has increased. if (partyAFee < arbitrationCost) { status = Status.WaitingPartyA; emit HasToPayFee(Party.PartyA); } else { // The partyA has also paid the fee. We create the dispute raiseDispute(arbitrationCost); } } /** @dev Create a dispute. UNTRUSTED. * @param _arbitrationCost Amount to pay the arbitrator. */ function raiseDispute(uint _arbitrationCost) internal { status = Status.DisputeCreated; disputeID = arbitrator.createDispute.value(_arbitrationCost)(amountOfChoices,arbitratorExtraData); emit Dispute(arbitrator, disputeID, 0, 0); } /** @dev Reimburse partyA if partyB fails to pay the fee. */ function timeOutByPartyA() public onlyPartyA { require(status == Status.WaitingPartyB, "Not waiting for party B."); require(now >= lastInteraction + timeout, "The timeout time has not passed."); executeRuling(disputeID,PARTY_A_WINS); } /** @dev Pay partyB if partyA fails to pay the fee. */ function timeOutByPartyB() public onlyPartyB { require(status == Status.WaitingPartyA, "Not waiting for party A."); require(now >= lastInteraction + timeout, "The timeout time has not passed."); executeRuling(disputeID,PARTY_B_WINS); } /** @dev Submit a reference to evidence. EVENT. * @param _evidence A link to an evidence using its URI. */ function submitEvidence(string _evidence) public onlyParty { require(status >= Status.DisputeCreated, "The dispute has not been created yet."); emit Evidence(arbitrator, 0, msg.sender, _evidence); } /** @dev Appeal an appealable ruling. * Transfer the funds to the arbitrator. * Note that no checks are required as the checks are done by the arbitrator. * @param _extraData Extra data for the arbitrator appeal procedure. */ function appeal(bytes _extraData) public onlyParty payable { arbitrator.appeal.value(msg.value)(disputeID,_extraData); } /** @dev Execute a ruling of a dispute. It reimburse the fee to the winning party. * This need to be extended by contract inheriting from it. * @param _disputeID ID of the dispute in the Arbitrator contract. * @param _ruling Ruling given by the arbitrator. 1 : Reimburse the partyA. 2 : Pay the partyB. */ function executeRuling(uint _disputeID, uint _ruling) internal { require(_disputeID == disputeID, "Wrong dispute ID."); require(_ruling <= amountOfChoices, "Invalid ruling."); // Give the arbitration fee back. // Note that we use send to prevent a party from blocking the execution. // In both cases sends the highest amount paid to avoid ETH to be stuck in // the contract if the arbitrator lowers its fee. if (_ruling==PARTY_A_WINS) partyA.send(partyAFee > partyBFee ? partyAFee : partyBFee); else if (_ruling==PARTY_B_WINS) partyB.send(partyAFee > partyBFee ? partyAFee : partyBFee); status = Status.Resolved; } } ``` # Rental.sol ```solidity pragma solidity ^0.4.15; import "./TwoPartyArbitrable.sol"; /** @title Rental * This is a a contract for rental agreement. * This can be used to rent objects or properties. * Party A is the renter. Party B is the owner. * Party A put a deposit. If everything goes well, it will be given back. * Otherwize parties can claim an amount of damages. If they disagree, the arbitrator will have to solve this dispute. */ contract Rental is TwoPartyArbitrable { string constant RULING_OPTIONS = "Rule for party A (renter);Rule for Party B (owner)"; uint8 constant AMOUNT_OF_CHOICES = 2; // The number of ruling options available. uint public amount; // Amount sent by party A. uint public damagesClaimedByPartyA; // The amount party A agrees to pay to compensate damages. uint public damagesClaimedByPartyB; // The amount party B claims to compensate damages. /** @dev Constructor. Choose the arbitrator. Should be called by party A (the payer). * @param _arbitrator The arbitrator of the contract. * @param _timeout Time after which a party automatically loose a dispute. * @param _partyB The owner. * @param _arbitratorExtraData Extra data for the arbitrator. * @param _metaEvidence Link to meta-evidence JSON. */ constructor( Arbitrator _arbitrator, uint _timeout, address _partyB, bytes _arbitratorExtraData, string _metaEvidence ) public TwoPartyArbitrable(_arbitrator,_timeout,_partyB,AMOUNT_OF_CHOICES,_arbitratorExtraData, _metaEvidence) payable { amount += msg.value; } /** @dev Claim an amount of damages. * Must be called before the dispute is created. * If the amount agreed is the same for both, pay it. * @param _damages The amount asked or agreed to be paid. */ function claimDamages(uint _damages) public onlyParty { // Make sure that parties can't change when a dispute already started. require(status < Status.DisputeCreated, "The dispute has already been created."); // Needed to avoid claiming 0 first and triggering an agreement. Use forfeitDeposit and unlockDeposit for the cases where 0 is claimed. require(_damages != 0, "There must be damages."); require(_damages <= amount, "Cannot claim more than balance."); // Make sure not to claim more than the contract has. if (msg.sender == partyA) damagesClaimedByPartyA = _damages; else damagesClaimedByPartyB = _damages; if (damagesClaimedByPartyA==damagesClaimedByPartyB) { // If there is an agreement. partyA.send((amount - damagesClaimedByPartyB) + partyAFee); partyB.send(damagesClaimedByPartyB + partyBFee); damagesClaimedByPartyA = 0; damagesClaimedByPartyB = 0; partyAFee = 0; partyBFee = 0; amount = 0; status = Status.Resolved; } } /** @dev Forfeit the deposit to party B. * To be called if the good has been completely broken or that the property damages exceed the deposit. */ function forfeitDeposit() public onlyPartyA { partyB.transfer(amount); amount = 0; } /** @dev Unlock party A deposit. To be called if the good or property has been returned without damages. */ function unlockDeposit() public onlyPartyB { partyA.transfer(amount); amount = 0; } /** @dev Execute a ruling of a dispute. It reimburse the fee to the winning party. * This need to be extended by contract inheriting from it. * @param _disputeID ID of the dispute in the Arbitrator contract. * @param _ruling Ruling given by the arbitrator. 1 : Rule for party A (renter). 2 : Rule for Party B (owner). */ function executeRuling(uint _disputeID, uint _ruling) internal { super.executeRuling(_disputeID,_ruling); if (_ruling == PARTY_A_WINS) { partyA.send(amount - damagesClaimedByPartyA); partyB.send(damagesClaimedByPartyA); } else if (_ruling == PARTY_B_WINS) { partyA.send(amount - damagesClaimedByPartyB); partyB.send(damagesClaimedByPartyB); } amount = 0; damagesClaimedByPartyA = 0; damagesClaimedByPartyB = 0; } } ``` # ArbitrableTransaction.sol ```solidity pragma solidity ^0.4.15; import "./TwoPartyArbitrable.sol"; /** @title Arbitrable Transaction * This is a a contract for an arbitrated transaction which can be reversed by the arbitrator. * This can be used for buying goods, services and for paying freelancers. * Party A is the payer. Party B is the payee. */ contract ArbitrableTransaction is TwoPartyArbitrable { string constant RULING_OPTIONS = "Reimburse partyA;Pay partyB"; uint8 constant AMOUNT_OF_CHOICES = 2; // The number of ruling options available. uint public amount; // Amount sent by party A. /** @dev Constructor. Choose the arbitrator. Should be called by party A (the payer). * @param _arbitrator The arbitrator of the contract. * @param _timeout Time after which a party automatically loose a dispute. * @param _partyB The recipient of the transaction. * @param _arbitratorExtraData Extra data for the arbitrator. * @param _metaEvidence Link to meta-evidence JSON. */ constructor( Arbitrator _arbitrator, uint _timeout, address _partyB, bytes _arbitratorExtraData, string _metaEvidence ) TwoPartyArbitrable(_arbitrator,_timeout,_partyB,AMOUNT_OF_CHOICES,_arbitratorExtraData, _metaEvidence) payable public { amount += msg.value; } /** @dev Pay the party B. To be called when the good is delivered or the service rendered. */ function pay() public onlyPartyA { partyB.transfer(amount); amount = 0; } /** @dev Reimburse party A. To be called if the good or service can't be fully provided. * @param _amountReimbursed Amount to reimburse in wei. */ function reimburse(uint _amountReimbursed) public onlyPartyB { require(_amountReimbursed <= amount, "Cannot reimburse an amount higher than the deposit."); partyA.transfer(_amountReimbursed); amount -= _amountReimbursed; } /** @dev Execute a ruling of a dispute. It reimburse the fee to the winning party. * This need to be extended by contract inheriting from it. * @param _disputeID ID of the dispute in the Arbitrator contract. * @param _ruling Ruling given by the arbitrator. 1 : Reimburse the partyA. 2 : Pay the partyB. */ function executeRuling(uint _disputeID, uint _ruling) internal { super.executeRuling(_disputeID,_ruling); if (_ruling==PARTY_A_WINS) partyA.send(amount); else if (_ruling==PARTY_B_WINS) partyB.send(amount); amount = 0; } } ``` # MultipleArbitrableTransaction.sol ```solidity pragma solidity ^0.4.24; import "./Arbitrator.sol"; import "./IArbitrable.sol"; /** @title Multiple Arbitrable Transaction * This is a contract for multiple arbitrated transactions which can be reversed by an arbitrator. * This can be used for buying goods, services and for paying freelancers. * Parties are identified as "sender" and "receiver". */ contract MultipleArbitrableTransaction is IArbitrable { // **************************** // // * Contract variables * // // **************************** // uint8 constant AMOUNT_OF_CHOICES = 2; uint8 constant SENDER_WINS = 1; uint8 constant RECEIVER_WINS = 2; enum Party {Sender, Receiver} enum Status {NoDispute, WaitingSender, WaitingReceiver, DisputeCreated, Resolved} struct Transaction { address sender; address receiver; uint amount; uint timeoutPayment; // Time in seconds after which the transaction can be automatically executed if not disputed. uint disputeId; // If dispute exists, the ID of the dispute. uint senderFee; // Total fees paid by the sender. uint receiverFee; // Total fees paid by the receiver. uint lastInteraction; // Last interaction for the dispute procedure. Status status; } Transaction[] public transactions; bytes public arbitratorExtraData; // Extra data to set up the arbitration. Arbitrator public arbitrator; // Address of the arbitrator contract. uint public feeTimeout; // Time in seconds a party can take to pay arbitration fees before being considered unresponding and lose the dispute. mapping (uint => uint) public disputeIDtoTransactionID; // One-to-one relationship between the dispute and the transaction. // **************************** // // * Events * // // **************************** // /** @dev To be emitted when a party pays or reimburses the other. * @param _transactionID The index of the transaction. * @param _amount The amount paid. * @param _party The party that paid. */ event Payment(uint indexed _transactionID, uint _amount, address _party); /** @dev Indicate that a party has to pay a fee or would otherwise be considered as losing. * @param _transactionID The index of the transaction. * @param _party The party who has to pay. */ event HasToPayFee(uint indexed _transactionID, Party _party); /** @dev To be raised when a ruling is given. * @param _arbitrator The arbitrator giving the ruling. * @param _disputeID ID of the dispute in the Arbitrator contract. * @param _ruling The ruling which was given. */ event Ruling(Arbitrator indexed _arbitrator, uint indexed _disputeID, uint _ruling); /** @dev Emitted when a transaction is created. * @param _transactionID The index of the transaction. * @param _sender The address of the sender. * @param _receiver The address of the receiver. * @param _amount The initial amount in the transaction. */ event TransactionCreated(uint _transactionID, address indexed _sender, address indexed _receiver, uint _amount); // **************************** // // * Arbitrable functions * // // * Modifying the state * // // **************************** // /** @dev Constructor. * @param _arbitrator The arbitrator of the contract. * @param _arbitratorExtraData Extra data for the arbitrator. * @param _feeTimeout Arbitration fee timeout for the parties. */ constructor ( Arbitrator _arbitrator, bytes _arbitratorExtraData, uint _feeTimeout ) public { arbitrator = _arbitrator; arbitratorExtraData = _arbitratorExtraData; feeTimeout = _feeTimeout; } /** @dev Create a transaction. * @param _timeoutPayment Time after which a party can automatically execute the arbitrable transaction. * @param _receiver The recipient of the transaction. * @param _metaEvidence Link to the meta-evidence. * @return transactionID The index of the transaction. */ function createTransaction( uint _timeoutPayment, address _receiver, string _metaEvidence ) public payable returns (uint transactionID) { transactions.push(Transaction({ sender: msg.sender, receiver: _receiver, amount: msg.value, timeoutPayment: _timeoutPayment, disputeId: 0, senderFee: 0, receiverFee: 0, lastInteraction: now, status: Status.NoDispute })); emit MetaEvidence(transactions.length - 1, _metaEvidence); emit TransactionCreated(transactions.length - 1, msg.sender, _receiver, msg.value); return transactions.length - 1; } /** @dev Pay receiver. To be called if the good or service is provided. * @param _transactionID The index of the transaction. * @param _amount Amount to pay in wei. */ function pay(uint _transactionID, uint _amount) public { Transaction storage transaction = transactions[_transactionID]; require(transaction.sender == msg.sender, "The caller must be the sender."); require(transaction.status == Status.NoDispute, "The transaction shouldn't be disputed."); require(_amount <= transaction.amount, "The amount paid has to be less than or equal to the transaction."); transaction.receiver.transfer(_amount); transaction.amount -= _amount; emit Payment(_transactionID, _amount, msg.sender); } /** @dev Reimburse sender. To be called if the good or service can't be fully provided. * @param _transactionID The index of the transaction. * @param _amountReimbursed Amount to reimburse in wei. */ function reimburse(uint _transactionID, uint _amountReimbursed) public { Transaction storage transaction = transactions[_transactionID]; require(transaction.receiver == msg.sender, "The caller must be the receiver."); require(transaction.status == Status.NoDispute, "The transaction shouldn't be disputed."); require(_amountReimbursed <= transaction.amount, "The amount reimbursed has to be less or equal than the transaction."); transaction.sender.transfer(_amountReimbursed); transaction.amount -= _amountReimbursed; emit Payment(_transactionID, _amountReimbursed, msg.sender); } /** @dev Transfer the transaction's amount to the receiver if the timeout has passed. * @param _transactionID The index of the transaction. */ function executeTransaction(uint _transactionID) public { Transaction storage transaction = transactions[_transactionID]; require(now - transaction.lastInteraction >= transaction.timeoutPayment, "The timeout has not passed yet."); require(transaction.status == Status.NoDispute, "The transaction shouldn't be disputed."); transaction.receiver.transfer(transaction.amount); transaction.amount = 0; transaction.status = Status.Resolved; } /** @dev Reimburse sender if receiver fails to pay the fee. * @param _transactionID The index of the transaction. */ function timeOutBySender(uint _transactionID) public { Transaction storage transaction = transactions[_transactionID]; require(transaction.status == Status.WaitingReceiver, "The transaction is not waiting on the receiver."); require(now - transaction.lastInteraction >= feeTimeout, "Timeout time has not passed yet."); if (transaction.receiverFee != 0) { transaction.receiver.send(transaction.receiverFee); transaction.receiverFee = 0; } executeRuling(_transactionID, SENDER_WINS); } /** @dev Pay receiver if sender fails to pay the fee. * @param _transactionID The index of the transaction. */ function timeOutByReceiver(uint _transactionID) public { Transaction storage transaction = transactions[_transactionID]; require(transaction.status == Status.WaitingSender, "The transaction is not waiting on the sender."); require(now - transaction.lastInteraction >= feeTimeout, "Timeout time has not passed yet."); if (transaction.senderFee != 0) { transaction.sender.send(transaction.senderFee); transaction.senderFee = 0; } executeRuling(_transactionID, RECEIVER_WINS); } /** @dev Pay the arbitration fee to raise a dispute. To be called by the sender. UNTRUSTED. * Note that the arbitrator can have createDispute throw, which will make this function throw and therefore lead to a party being timed-out. * This is not a vulnerability as the arbitrator can rule in favor of one party anyway. * @param _transactionID The index of the transaction. */ function payArbitrationFeeBySender(uint _transactionID) public payable { Transaction storage transaction = transactions[_transactionID]; uint arbitrationCost = arbitrator.arbitrationCost(arbitratorExtraData); require(transaction.status < Status.DisputeCreated, "Dispute has already been created or because the transaction has been executed."); require(msg.sender == transaction.sender, "The caller must be the sender."); transaction.senderFee += msg.value; // Require that the total pay at least the arbitration cost. require(transaction.senderFee >= arbitrationCost, "The sender fee must cover arbitration costs."); transaction.lastInteraction = now; // The receiver still has to pay. This can also happen if he has paid, but arbitrationCost has increased. if (transaction.receiverFee < arbitrationCost) { transaction.status = Status.WaitingReceiver; emit HasToPayFee(_transactionID, Party.Receiver); } else { // The receiver has also paid the fee. We create the dispute. raiseDispute(_transactionID, arbitrationCost); } } /** @dev Pay the arbitration fee to raise a dispute. To be called by the receiver. UNTRUSTED. * Note that this function mirrors payArbitrationFeeBySender. * @param _transactionID The index of the transaction. */ function payArbitrationFeeByReceiver(uint _transactionID) public payable { Transaction storage transaction = transactions[_transactionID]; uint arbitrationCost = arbitrator.arbitrationCost(arbitratorExtraData); require(transaction.status < Status.DisputeCreated, "Dispute has already been created or because the transaction has been executed."); require(msg.sender == transaction.receiver, "The caller must be the receiver."); transaction.receiverFee += msg.value; // Require that the total paid to be at least the arbitration cost. require(transaction.receiverFee >= arbitrationCost, "The receiver fee must cover arbitration costs."); transaction.lastInteraction = now; // The sender still has to pay. This can also happen if he has paid, but arbitrationCost has increased. if (transaction.senderFee < arbitrationCost) { transaction.status = Status.WaitingSender; emit HasToPayFee(_transactionID, Party.Sender); } else { // The sender has also paid the fee. We create the dispute. raiseDispute(_transactionID, arbitrationCost); } } /** @dev Create a dispute. UNTRUSTED. * @param _transactionID The index of the transaction. * @param _arbitrationCost Amount to pay the arbitrator. */ function raiseDispute(uint _transactionID, uint _arbitrationCost) internal { Transaction storage transaction = transactions[_transactionID]; transaction.status = Status.DisputeCreated; transaction.disputeId = arbitrator.createDispute.value(_arbitrationCost)(AMOUNT_OF_CHOICES, arbitratorExtraData); disputeIDtoTransactionID[transaction.disputeId] = _transactionID; emit Dispute(arbitrator, transaction.disputeId, _transactionID, _transactionID); // Refund sender if it overpaid. if (transaction.senderFee > _arbitrationCost) { uint extraFeeSender = transaction.senderFee - _arbitrationCost; transaction.senderFee = _arbitrationCost; transaction.sender.send(extraFeeSender); } // Refund receiver if it overpaid. if (transaction.receiverFee > _arbitrationCost) { uint extraFeeReceiver = transaction.receiverFee - _arbitrationCost; transaction.receiverFee = _arbitrationCost; transaction.receiver.send(extraFeeReceiver); } } /** @dev Submit a reference to evidence. EVENT. * @param _transactionID The index of the transaction. * @param _evidence A link to an evidence using its URI. */ function submitEvidence(uint _transactionID, string _evidence) public { Transaction storage transaction = transactions[_transactionID]; require( msg.sender == transaction.sender || msg.sender == transaction.receiver, "The caller must be the sender or the receiver." ); require( transaction.status < Status.Resolved, "Must not send evidence if the dispute is resolved." ); emit Evidence(arbitrator, _transactionID, msg.sender, _evidence); } /** @dev Appeal an appealable ruling. * Transfer the funds to the arbitrator. * Note that no checks are required as the checks are done by the arbitrator. * @param _transactionID The index of the transaction. */ function appeal(uint _transactionID) public payable { Transaction storage transaction = transactions[_transactionID]; arbitrator.appeal.value(msg.value)(transaction.disputeId, arbitratorExtraData); } /** @dev Give a ruling for a dispute. Must be called by the arbitrator. * The purpose of this function is to ensure that the address calling it has the right to rule on the contract. * @param _disputeID ID of the dispute in the Arbitrator contract. * @param _ruling Ruling given by the arbitrator. Note that 0 is reserved for "Not able/wanting to make a decision". */ function rule(uint _disputeID, uint _ruling) public { uint transactionID = disputeIDtoTransactionID[_disputeID]; Transaction storage transaction = transactions[transactionID]; require(msg.sender == address(arbitrator), "The caller must be the arbitrator."); require(transaction.status == Status.DisputeCreated, "The dispute has already been resolved."); emit Ruling(Arbitrator(msg.sender), _disputeID, _ruling); executeRuling(transactionID, _ruling); } /** @dev Execute a ruling of a dispute. It reimburses the fee to the winning party. * @param _transactionID The index of the transaction. * @param _ruling Ruling given by the arbitrator. 1 : Reimburse the receiver. 2 : Pay the sender. */ function executeRuling(uint _transactionID, uint _ruling) internal { Transaction storage transaction = transactions[_transactionID]; require(_ruling <= AMOUNT_OF_CHOICES, "Invalid ruling."); // Give the arbitration fee back. // Note that we use send to prevent a party from blocking the execution. if (_ruling == SENDER_WINS) { transaction.sender.send(transaction.senderFee + transaction.amount); } else if (_ruling == RECEIVER_WINS) { transaction.receiver.send(transaction.receiverFee + transaction.amount); } else { uint split_amount = (transaction.senderFee + transaction.amount) / 2; transaction.sender.send(split_amount); transaction.receiver.send(split_amount); } transaction.amount = 0; transaction.senderFee = 0; transaction.receiverFee = 0; transaction.status = Status.Resolved; } // **************************** // // * Constant getters * // // **************************** // /** @dev Getter to know the count of transactions. * @return countTransactions The count of transactions. */ function getCountTransactions() public view returns (uint countTransactions) { return transactions.length; } /** @dev Get IDs for transactions where the specified address is the receiver and/or the sender. * This function must be used by the UI and not by other smart contracts. * Note that the complexity is O(t), where t is amount of arbitrable transactions. * @param _address The specified address. * @return transactionIDs The transaction IDs. */ function getTransactionIDsByAddress(address _address) public view returns (uint[] transactionIDs) { uint count = 0; for (uint i = 0; i < transactions.length; i++) { if (transactions[i].sender == _address || transactions[i].receiver == _address) count++; } transactionIDs = new uint[](count); count = 0; for (uint j = 0; j < transactions.length; j++) { if (transactions[j].sender == _address || transactions[j].receiver == _address) transactionIDs[count++] = j; } } } ``` # MultipleArbitrableTokenTransaction.sol ```solidity pragma solidity ^0.4.24; import "./Arbitrator.sol"; import "./IArbitrable.sol"; import "@openzeppelin/contracts/token/ERC20/ERC20.sol"; /** @title Multiple Arbitrable ERC20 Token Transaction * This is a contract for multiple arbitrated token transactions which can be reversed by an arbitrator. * This can be used for buying goods, services and for paying freelancers. * Parties are identified as "sender" and "receiver". */ contract MultipleArbitrableTokenTransaction is IArbitrable { // **************************** // // * Contract variables * // // **************************** // uint8 constant AMOUNT_OF_CHOICES = 2; enum Party {Sender, Receiver} enum Status {NoDispute, WaitingSender, WaitingReceiver, DisputeCreated, Resolved} enum RulingOptions {NoRuling, SenderWins, ReceiverWins} struct Transaction { address sender; address receiver; uint amount; ERC20 token; uint timeoutPayment; // Time in seconds after which the transaction can be automatically executed if not disputed. uint disputeId; // If dispute exists, the ID of the dispute. uint senderFee; // Total fees paid by the sender. uint receiverFee; // Total fees paid by the receiver. uint lastInteraction; // Last interaction for the dispute procedure. Status status; } Transaction[] public transactions; Arbitrator public arbitrator; // Address of the arbitrator contract. bytes public arbitratorExtraData; // Extra data to set up the arbitration. uint public feeTimeout; // Time in seconds a party can take to pay arbitration fees before being considered unresponding and lose the dispute. mapping (uint => uint) public disputeIDtoTransactionID; // **************************** // // * Events * // // **************************** // /** @dev To be emitted when a party pays or reimburses the other. * @param _transactionID The index of the transaction. * @param _amount The amount paid. * @param _party The party that paid. */ event Payment(uint indexed _transactionID, uint _amount, address _party); /** @dev Indicate that a party has to pay a fee or would otherwise be considered as losing. * @param _transactionID The index of the transaction. * @param _party The party who has to pay. */ event HasToPayFee(uint indexed _transactionID, Party _party); /** @dev Emitted when the final ruling of a dispute is given by the arbitrator. * @param _arbitrator The arbitrator giving the ruling. * @param _disputeID ID of the dispute in the Arbitrator contract. * @param _ruling The ruling which was given. */ event Ruling(Arbitrator indexed _arbitrator, uint indexed _disputeID, uint _ruling); /** @dev Emitted when a transaction is created. * @param _transactionID The index of the transaction. * @param _sender The address of the sender. * @param _receiver The address of the receiver. * @param _token The token address. * @param _amount The initial amount of the token. */ event TransactionCreated(uint _transactionID, address indexed _sender, address indexed _receiver, ERC20 _token, uint _amount); // **************************** // // * Arbitrable functions * // // * Modifying the state * // // **************************** // /** @dev Constructor. * @param _arbitrator The arbitrator of the contract. * @param _arbitratorExtraData Extra data for the arbitrator. * @param _feeTimeout Arbitration fee timeout for the parties. */ constructor ( Arbitrator _arbitrator, bytes _arbitratorExtraData, uint _feeTimeout ) public { arbitrator = _arbitrator; arbitratorExtraData = _arbitratorExtraData; feeTimeout = _feeTimeout; } /** @dev Create a transaction. UNTRUSTED. * @param _amount The amount of tokens in this transaction. * @param _token The ERC20 token contract. * @param _timeoutPayment Time after which a party automatically loses a dispute. * @param _receiver The recipient of the transaction. * @param _metaEvidence Link to the meta-evidence. * @return The index of the transaction. */ function createTransaction( uint _amount, ERC20 _token, uint _timeoutPayment, address _receiver, string _metaEvidence ) public returns (uint transactionIndex) { // Transfers token from sender wallet to contract. require(_token.transferFrom(msg.sender, address(this), _amount), "Sender does not have enough approved funds."); transactions.push(Transaction({ sender: msg.sender, receiver: _receiver, amount: _amount, token: _token, timeoutPayment: _timeoutPayment, disputeId: 0, senderFee: 0, receiverFee: 0, lastInteraction: now, status: Status.NoDispute })); emit MetaEvidence(transactions.length - 1, _metaEvidence); emit TransactionCreated(transactions.length - 1, msg.sender, _receiver, _token, _amount); return transactions.length - 1; } /** @dev Pay receiver. To be called if the good or service is provided. UNTRUSTED. * @param _transactionID The index of the transaction. * @param _amount Amount to pay in tokens. */ function pay(uint _transactionID, uint _amount) public { Transaction storage transaction = transactions[_transactionID]; require(transaction.sender == msg.sender, "The caller must be the sender."); require(transaction.status == Status.NoDispute, "The transaction shouldn't be disputed."); require(_amount <= transaction.amount, "The amount paid has to be less or equal than the transaction."); transaction.amount -= _amount; require(transaction.token.transfer(transaction.receiver, _amount), "The `transfer` function must not fail."); emit Payment(_transactionID, _amount, msg.sender); } /** @dev Reimburse sender. To be called if the good or service can't be fully provided. UNTRUSTED. * @param _transactionID The index of the transaction. * @param _amountReimbursed Amount to reimburse in tokens. */ function reimburse(uint _transactionID, uint _amountReimbursed) public { Transaction storage transaction = transactions[_transactionID]; require(transaction.receiver == msg.sender, "The caller must be the receiver."); require(transaction.status == Status.NoDispute, "The transaction shouldn't be disputed."); require(_amountReimbursed <= transaction.amount, "The amount reimbursed has to be less or equal than the transaction."); transaction.amount -= _amountReimbursed; require(transaction.token.transfer(transaction.sender, _amountReimbursed), "The `transfer` function must not fail."); emit Payment(_transactionID, _amountReimbursed, msg.sender); } /** @dev Transfer the transaction's amount to the receiver if the timeout has passed. UNTRUSTED. * @param _transactionID The index of the transaction. */ function executeTransaction(uint _transactionID) public { Transaction storage transaction = transactions[_transactionID]; require(now - transaction.lastInteraction >= transaction.timeoutPayment, "The timeout has not passed yet."); require(transaction.status == Status.NoDispute, "The transaction shouldn't be disputed."); uint amount = transaction.amount; transaction.amount = 0; transaction.status = Status.Resolved; require(transaction.token.transfer(transaction.receiver, amount), "The `transfer` function must not fail."); } /** @dev Reimburse sender if receiver fails to pay the fee. UNTRUSTED. * @param _transactionID The index of the transaction. */ function timeOutBySender(uint _transactionID) public { Transaction storage transaction = transactions[_transactionID]; require(transaction.status == Status.WaitingReceiver, "The transaction is not waiting on the receiver."); require(now - transaction.lastInteraction >= feeTimeout, "Timeout time has not passed yet."); if (transaction.receiverFee != 0) { transaction.receiver.send(transaction.receiverFee); transaction.receiverFee = 0; } executeRuling(_transactionID, uint(RulingOptions.SenderWins)); } /** @dev Pay receiver if sender fails to pay the fee. UNTRUSTED. * @param _transactionID The index of the transaction. */ function timeOutByReceiver(uint _transactionID) public { Transaction storage transaction = transactions[_transactionID]; require(transaction.status == Status.WaitingSender, "The transaction is not waiting on the sender."); require(now - transaction.lastInteraction >= feeTimeout, "Timeout time has not passed yet."); if (transaction.senderFee != 0) { transaction.sender.send(transaction.senderFee); transaction.senderFee = 0; } executeRuling(_transactionID, uint(RulingOptions.ReceiverWins)); } /** @dev Pay the arbitration fee to raise a dispute. To be called by the sender. UNTRUSTED. * Note that the arbitrator can have `createDispute` throw, which will make this function throw and therefore lead to a party being timed-out. * This is not a vulnerability as the arbitrator can rule in favor of one party anyway. * @param _transactionID The index of the transaction. */ function payArbitrationFeeBySender(uint _transactionID) public payable { Transaction storage transaction = transactions[_transactionID]; uint arbitrationCost = arbitrator.arbitrationCost(arbitratorExtraData); require(transaction.status < Status.DisputeCreated, "Dispute has already been created."); require(msg.sender == transaction.sender, "The caller must be the sender."); transaction.senderFee += msg.value; // Require that the total paid to be at least the arbitration cost. require(transaction.senderFee >= arbitrationCost, "The sender fee must cover arbitration costs."); transaction.lastInteraction = now; // The receiver still has to pay. This can also happen if he has paid, but `arbitrationCost` has increased. if (transaction.receiverFee < arbitrationCost) { transaction.status = Status.WaitingReceiver; emit HasToPayFee(_transactionID, Party.Receiver); } else { // The receiver has also paid the fee. We create the dispute. raiseDispute(_transactionID, arbitrationCost); } } /** @dev Pay the arbitration fee to raise a dispute. To be called by the receiver. UNTRUSTED. * Note that this function mirrors payArbitrationFeeBySender. * @param _transactionID The index of the transaction. */ function payArbitrationFeeByReceiver(uint _transactionID) public payable { Transaction storage transaction = transactions[_transactionID]; uint arbitrationCost = arbitrator.arbitrationCost(arbitratorExtraData); require(transaction.status < Status.DisputeCreated, "Dispute has already been created."); require(msg.sender == transaction.receiver, "The caller must be the receiver."); transaction.receiverFee += msg.value; // Require that the total paid to be at least the arbitration cost. require(transaction.receiverFee >= arbitrationCost, "The receiver fee must cover arbitration costs."); transaction.lastInteraction = now; // The sender still has to pay. This can also happen if he has paid, but arbitrationCost has increased. if (transaction.senderFee < arbitrationCost) { transaction.status = Status.WaitingSender; emit HasToPayFee(_transactionID, Party.Sender); } else { // The sender has also paid the fee. We create the dispute. raiseDispute(_transactionID, arbitrationCost); } } /** @dev Create a dispute. UNTRUSTED. * @param _transactionID The index of the transaction. * @param _arbitrationCost Amount to pay the arbitrator. */ function raiseDispute(uint _transactionID, uint _arbitrationCost) internal { Transaction storage transaction = transactions[_transactionID]; transaction.status = Status.DisputeCreated; transaction.disputeId = arbitrator.createDispute.value(_arbitrationCost)(AMOUNT_OF_CHOICES, arbitratorExtraData); disputeIDtoTransactionID[transaction.disputeId] = _transactionID; emit Dispute(arbitrator, transaction.disputeId, _transactionID, _transactionID); // Refund sender if it overpaid. if (transaction.senderFee > _arbitrationCost) { uint extraFeeSender = transaction.senderFee - _arbitrationCost; transaction.senderFee = _arbitrationCost; transaction.sender.send(extraFeeSender); } // Refund receiver if it overpaid. if (transaction.receiverFee > _arbitrationCost) { uint extraFeeReceiver = transaction.receiverFee - _arbitrationCost; transaction.receiverFee = _arbitrationCost; transaction.receiver.send(extraFeeReceiver); } } /** @dev Submit a reference to evidence. EVENT. * @param _transactionID The index of the transaction. * @param _evidence A link to an evidence using its URI. */ function submitEvidence(uint _transactionID, string _evidence) public { Transaction storage transaction = transactions[_transactionID]; require( msg.sender == transaction.receiver || msg.sender == transaction.sender, "The caller must be the receiver or the sender." ); require( transaction.status < Status.Resolved, "Must not send evidence if the dispute is resolved." ); emit Evidence(arbitrator, _transactionID, msg.sender, _evidence); } /** @dev Appeal an appealable ruling. UNTRUSTED. * Transfer the funds to the arbitrator. * Note that no checks are required as the checks are done by the arbitrator. * @param _transactionID The index of the transaction. */ function appeal(uint _transactionID) public payable { Transaction storage transaction = transactions[_transactionID]; arbitrator.appeal.value(msg.value)(transaction.disputeId, arbitratorExtraData); } /** @dev Give a ruling for a dispute. Must be called by the arbitrator to enforce the final ruling. * The purpose of this function is to ensure that the address calling it has the right to rule on the contract. * @param _disputeID ID of the dispute in the Arbitrator contract. * @param _ruling Ruling given by the arbitrator. Note that 0 is reserved for "Not able/wanting to make a decision". */ function rule(uint _disputeID, uint _ruling) public { uint transactionID = disputeIDtoTransactionID[_disputeID]; Transaction storage transaction = transactions[transactionID]; require(msg.sender == address(arbitrator), "The caller must be the arbitrator."); require(transaction.status == Status.DisputeCreated, "The dispute has already been resolved."); emit Ruling(Arbitrator(msg.sender), _disputeID, _ruling); executeRuling(transactionID, _ruling); } /** @dev Execute a ruling of a dispute. It reimburses the fee to the winning party. * @param _transactionID The index of the transaction. * @param _ruling Ruling given by the arbitrator. 1: Reimburse the receiver. 2: Pay the sender. */ function executeRuling(uint _transactionID, uint _ruling) internal { Transaction storage transaction = transactions[_transactionID]; require(_ruling <= AMOUNT_OF_CHOICES, "Invalid ruling."); uint amount = transaction.amount; uint senderFee = transaction.senderFee; uint receiverFee = transaction.receiverFee; transaction.amount = 0; transaction.senderFee = 0; transaction.receiverFee = 0; transaction.status = Status.Resolved; // Give the arbitration fee back. // Note that we use `send` to prevent a party from blocking the execution. if (_ruling == uint(RulingOptions.SenderWins)) { transaction.sender.send(senderFee); require(transaction.token.transfer(transaction.sender, amount), "The `transfer` function must not fail."); } else if (_ruling == uint(RulingOptions.ReceiverWins)) { transaction.receiver.send(receiverFee); require(transaction.token.transfer(transaction.receiver, amount), "The `transfer` function must not fail."); } else { // `senderFee` and `receiverFee` are equal to the arbitration cost. uint splitArbitrationFee = senderFee / 2; transaction.receiver.send(splitArbitrationFee); transaction.sender.send(splitArbitrationFee); // Tokens should not reenter or allow recipients to refuse the transfer. // In the case of an uneven token amount, one basic token unit can be burnt. require(transaction.token.transfer(transaction.receiver, amount / 2), "The `transfer` function must not fail."); require(transaction.token.transfer(transaction.sender, amount / 2), "The `transfer` function must not fail."); } } // **************************** // // * Constant getters * // // **************************** // /** @dev Getter to know the count of transactions. * @return countTransactions The count of transactions. */ function getCountTransactions() public view returns (uint countTransactions) { return transactions.length; } /** @dev Get IDs for transactions where the specified address is the receiver and/or the sender. * This function must be used by the UI and not by other smart contracts. * Note that the complexity is O(t), where t is amount of arbitrable transactions. * @param _address The specified address. * @return transactionIDs The transaction IDs. */ function getTransactionIDsByAddress(address _address) public view returns (uint[] transactionIDs) { uint count = 0; for (uint i = 0; i < transactions.length; i++) { if (transactions[i].sender == _address || transactions[i].receiver == _address) count++; } transactionIDs = new uint[](count); count = 0; for (uint j = 0; j < transactions.length; j++) { if (transactions[j].sender == _address || transactions[j].receiver == _address) transactionIDs[count++] = j; } } } ``` # Deployment Addresses Contracts are categorized as Core (actively used in production) or Non-core / Legacy (deprecated, superseded, or low-activity). ## Mainnet ### Ethereum #### Core | Contract | Address | | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- | | KlerosLiquid | [0x988b3A538b618C7A603e1c11Ab82Cd16dbE28069](https://etherscan.io/address/0x988b3A538b618C7A603e1c11Ab82Cd16dbE28069) | | PNK | [0x93ED3FBe21207Ec2E8f2d3c3de6e058Cb73Bc04d](https://etherscan.io/address/0x93ED3FBe21207Ec2E8f2d3c3de6e058Cb73Bc04d) | | PolicyRegistry | [0xcf1f07713d5193fae5c1653c9f61953d048bece4](https://etherscan.io/address/0xcf1f07713d5193fae5c1653c9f61953d048bece4) | | SortitionSumTreeFactory | [0x180eba68d164c3f8c3f6dc354125ebccf4dfcb86](https://etherscan.io/address/0x180eba68d164c3f8c3f6dc354125ebccf4dfcb86) | | KlerosLiquid Extra Views | [0x2B562ea613ad2f58746935C842d09EB147E1E940](https://etherscan.io/address/0x2B562ea613ad2f58746935C842d09EB147E1E940) | | Governor (kleros.eth) | [0xe5bcEa6F87aAEe4a81f64dfDB4d30d400e0e5cf4](https://etherscan.io/address/0xe5bcEa6F87aAEe4a81f64dfDB4d30d400e0e5cf4) | | ArbitrableProxy | [0x99489d7bb33539f3d1a401741e56e8f02b9ae0cf](https://etherscan.io/address/0x99489d7bb33539f3d1a401741e56e8f02b9ae0cf) | | Transaction Batcher | [0x82458d1c812d7c930bb3229c9e159cbabd9aa8cb](https://etherscan.io/address/0x82458d1c812d7c930bb3229c9e159cbabd9aa8cb) | | RNGenerator | [0x90992fb4E15ce0C59aEFfb376460Fda4Ee19C879](https://etherscan.io/address/0x90992fb4E15ce0C59aEFfb376460Fda4Ee19C879) | | Realitio Proxy 2.1 With Appeals (General Purpose) | [0x728cba71a3723caab33ea416cb46e2cc9215a596](https://etherscan.io/address/0x728cba71a3723caab33ea416cb46e2cc9215a596) | | Realitio Proxy 2.1 With Appeals (Gnosis Zodiac) | [0xf72cfd1b34a91a64f9a98537fe63fbab7530adca](https://etherscan.io/address/0xf72cfd1b34a91a64f9a98537fe63fbab7530adca) | | Realitio Cross-chain xDAI Foreign Proxy (Realitio 2.1) | [0x79d0464ec27f67663dadf761432fc8dd0aea3d49](https://etherscan.io/address/0x79d0464ec27f67663dadf761432fc8dd0aea3d49) | | Realitio Cross-chain Polygon Foreign Proxy | [0x776e5853e3d61b2dfb22bcf872a43bf9a1231e52](https://etherscan.io/address/0x776e5853e3d61b2dfb22bcf872a43bf9a1231e52) | | KlerosConnector for Unslashed | [0xe0e1bc8C6cd1B81993e2Fcfb80832d814886eA38](https://etherscan.io/address/0xe0e1bc8C6cd1B81993e2Fcfb80832d814886eA38) | | ArbitrableTokenList (T2CR) | [0xebcf3bca271b26ae4b162ba560e243055af0e679](https://etherscan.io/address/0xebcf3bca271b26ae4b162ba560e243055af0e679) | | Proof of Humanity | [0xC5E9dDebb09Cd64DfaCab4011A0D5cEDaf7c9BDb](https://etherscan.io/address/0xC5E9dDebb09Cd64DfaCab4011A0D5cEDaf7c9BDb) | | Kleros Linguo Contracts | See [here](https://github.com/kleros/linguo-contracts/tree/master/deployments/mainnet). | **Non-core / Legacy** | Contract | Address | | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | Governor (poh.eth) | [0x327a29fcE0a6490E4236240Be176dAA282EcCfdF](https://etherscan.io/address/0x327a29fcE0a6490E4236240Be176dAA282EcCfdF) | | Governor (ubi-voting.eth) | [0x7510c77163683448b8Dc8fe9e019d9482Be1ed2b](https://etherscan.io/address/0x7510c77163683448b8Dc8fe9e019d9482Be1ed2b) | | Governor (fork-dao.eth) | [0xf7dE5537eCD69a94695fcF4BCdBDeE6329b63322](https://etherscan.io/address/0xf7dE5537eCD69a94695fcF4BCdBDeE6329b63322) | | Realitio Arbitrator Proxy (original, no appeals) | [0xd47f72a2d1d0e91b0ec5e5f5d02b2dc26d00a14d](https://etherscan.io/address/0xd47f72a2d1d0e91b0ec5e5f5d02b2dc26d00a14d) | | Realitio Cross-Chain xDAI Foreign Proxy (non-2.1) | [0x2f0895732bfacdcf2fdb19962fe609d0da695f21](https://etherscan.io/address/0x2f0895732bfacdcf2fdb19962fe609d0da695f21) | | Escrow (ETH) | [0x0d67440946949FE293B45c52eFD8A9b3d51e2522](https://etherscan.io/address/0x0d67440946949FE293B45c52eFD8A9b3d51e2522) | | ArbitrableAddressList (Ethfinex) | [0x916deab80dfbc7030277047cd18b233b3ce5b4ab](https://etherscan.io/address/0x916deab80dfbc7030277047cd18b233b3ce5b4ab) | | ArbitrableAddressList (ERC20) | [0xCb4Aae35333193232421E86Cd2E9b6C91f3B125F](https://etherscan.io/address/0xCb4Aae35333193232421E86Cd2E9b6C91f3B125F) | | UBI Pool | [0xa27bfea336bc7058ff1297eeff2732389f8b208f](https://etherscan.io/address/0xa27bfea336bc7058ff1297eeff2732389f8b208f) | | UBI ProxyAdmin | [0x2b59500ad441bf5accf8ff89449552b6487132e0](https://etherscan.io/address/0x2b59500ad441bf5accf8ff89449552b6487132e0) | ### Gnosis Chain **Core** | Contract | Address | | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | xKlerosLiquid | [0x9C1dA9A04925bDfDedf0f6421bC7EEa8305F9002](https://gnosisscan.io/address/0x9C1dA9A04925bDfDedf0f6421bC7EEa8305F9002) | | wrappedPNK | [0xcb3231aBA3b451343e0Fddfc45883c842f223846](https://gnosisscan.io/address/0xcb3231aBA3b451343e0Fddfc45883c842f223846) | | PolicyRegistry | [0x9d494768936b6bDaabc46733b8D53A937A6c6D7e](https://gnosisscan.io/address/0x9d494768936b6bDaabc46733b8D53A937A6c6D7e) | | KlerosLiquid/PNK ProxyAdmin | [0xD1a711a863aFB85D1b4E721DcB3e48C477E46475](https://gnosisscan.io/address/0xD1a711a863aFB85D1b4E721DcB3e48C477E46475) | | KlerosLiquid Extra Views | [0xFA71f907B48f27d22f670d9E446f8137b0769e4B](https://gnosisscan.io/address/0xFA71f907B48f27d22f670d9E446f8137b0769e4B) | | SortitionSumTreeFactory | [0x7AE716d9935F41F173D944FE6557c1e117d561E9](https://gnosisscan.io/address/0x7AE716d9935F41F173D944FE6557c1e117d561E9) | | Transaction Batcher | [0x6426800F8508b15AED271337498fa5e7D0794d46](https://gnosisscan.io/address/0x6426800F8508b15AED271337498fa5e7D0794d46) | | Realitio Cross-Chain xDAI Home Proxy | [0x29f39de98d750eb77b5fafb31b2837f079fce222](https://gnosisscan.io/address/0x29f39de98d750eb77b5fafb31b2837f079fce222) | | Realitio v2.1 with Appeals (for Moderate) | [0xe04f5791d671d5C4e08ab49b39807087B591ea3e](https://gnosisscan.io/address/0xe04f5791d671d5C4e08ab49b39807087B591ea3e) | | Realitio Cross-chain xDAI Home Proxy (2.1) — Omen | [0xe40DD83a262da3f56976038F1554Fe541Fa75ecd](https://gnosisscan.io/address/0xe40DD83a262da3f56976038F1554Fe541Fa75ecd) | | LGTCR Tokens | [0x70533554fe5c17CAf77fE530f77eAB933B92af60](https://gnosisscan.io/address/0x70533554fe5c17CAf77fE530f77eAB933B92af60) | | LGTCR Address Tags | [0x66260C69d03837016d88c9877e61e08Ef74C59F2](https://gnosisscan.io/address/0x66260C69d03837016d88c9877e61e08Ef74C59F2) | | LGTCR Contract Domain Names | [0x957A53A994860BE4750810131d9c876b2f52d6E1](https://gnosisscan.io/address/0x957A53A994860BE4750810131d9c876b2f52d6E1) | | Kleros Linguo Contracts | See [here](https://github.com/kleros/linguo-contracts/tree/master/deployments/xdai). | ### Polygon
ContractAddress

Realitio Cross-Chain

Polygon Home Proxy

0x5AFa42b30955f137e10f89dfb5EF1542a186F90e
### Arbitrum One Always verify a Kleros V2 address against the [V2 deployment list](https://github.com/kleros/kleros-v2/tree/master/contracts/deployments) before. **Core** | Contract | Address | | ----------------------- | -------------------------------------------------------------------------------------------------------------------- | | PNK | [0x330bd769382cfc6d50175903434ccc8d206dcae5](https://arbiscan.io/address/0x330bd769382cfc6d50175903434ccc8d206dcae5) | | KlerosCore (Proxy) | [0x991d2df165670b9cac3B022f4B68D65b664222ea](https://arbiscan.io/address/0x991d2df165670b9cac3B022f4B68D65b664222ea) | | SortitionModule (Proxy) | [0x21A9402aDb818744B296e1d1BE58C804118DC03D](https://arbiscan.io/address/0x21A9402aDb818744B296e1d1BE58C804118DC03D) | | DisputeResolver | [0xb5526D022962A1fFf6eD32C93e8b714c901F4323](https://arbiscan.io/address/0xb5526D022962A1fFf6eD32C93e8b714c901F4323) | | EvidenceModule (Proxy) | [0x48e052B4A6dC4F30e90930F1CeaAFd83b3981EB3](https://arbiscan.io/address/0x48e052B4A6dC4F30e90930F1CeaAFd83b3981EB3) | | ChainlinkRNG | [0x897d83a7d5F23555eFA15e1BE297d5503522cbA3](https://arbiscan.io/address/0x897d83a7d5F23555eFA15e1BE297d5503522cbA3) | | RandomizerRNG (Proxy) | [0x044AfE0069C0fd641BC5f90d9A4218eF0b2Fa9d3](https://arbiscan.io/address/0x044AfE0069C0fd641BC5f90d9A4218eF0b2Fa9d3) | | TransactionBatcher | [0xBC5ef8d9ad307154447AE148c088f083d2dEa4eF](https://arbiscan.io/address/0xBC5ef8d9ad307154447AE148c088f083d2dEa4eF) | **Non-core / Legacy** | Contract | Address | | ------------------------- | -------------------------------------------------------------------------------------------------------------------- | | DisputeKitShutter (Proxy) | [0x9D3e3f1765744c2a1BC6F6088549770444BBC768](https://arbiscan.io/address/0x9D3e3f1765744c2a1BC6F6088549770444BBC768) | | BlockHashRNG | [0x39D123fc4cFD24EA5bB76195f9ecFE1f0DF35b0B](https://arbiscan.io/address/0x39D123fc4cFD24EA5bB76195f9ecFE1f0DF35b0B) | | KlerosV2NeoEarlyUser | [0xfE34a72c55e512601E7d491A9c5b36373cE34d63](https://arbiscan.io/address/0xfE34a72c55e512601E7d491A9c5b36373cE34d63) | ## Testnets ### Sepolia
ContractAddress
KlerosLiquid0x90992fb4E15ce0C59aEFfb376460Fda4Ee19C879
KlerosLiquidExtraViews0x5562Ac605764DC4039fb6aB56a74f7321396Cdf2
PNK0xA1eE4D32bdBcA69cdb445D66fAA3804aFFa24bFE
PNK Faucet0x776e5853e3d61B2dFB22Bcf872a43bF9A1231e52
TransactionBatcher0x56Cf53B9B8FAE2f8956F1aDc9540B2E03Ebf3665
Realitio Proxy0x05b942faecfb3924970e3a28e0f230910cedff45
PolicyRegistry0x88Fb25D399310c07d35cB9091b8346d8b1893aa5
### Chiado
ContractAddress
xKlerosLiquid0xD8798DfaE8194D6B4CD6e2Da6187ae4209d06f27
xKlerosLiquidExtraViews0xfDD698D6c9393d08c5DaD8488AF6d08c151e4860
PNK0xA353A70c8B3C7d38A869436d4CDeBe8e5611681a
PNK Faucet0x4163BEeb923A06837BaE3Ee1999CcdB9CD606362
TransactionBatcher0xA2c538AA05BBCc44c213441f6f3777223D2BF9e5
ArbitrableProxy0x4BEf0321BD7fa943f85ae55e07f790c6beCbd177
PolicyRegistry0x53FC70FE1EC3a60f8939A62aBCc61bf1A57938D7
# Curate Classic: Integration for Devs The Kleros-powered [TCR factory and browser](https://curate.kleros.io). ## Introduction Curate is a web app built to ease interaction with Generalized TCR contracts. With it, users can create new TCRs (a.k.a. lists), browse deployed lists and interact with them (submit, remove or challenge items). Decentralized curated lists are most useful as a replacement for apps that do curation without tripartition of powers. Some examples of apps that do this (and often generate frustation for users) are: * Social Media; * App Stores; * News Platforms; * Video Platforms; * Content Storage; The status quo is that central parties get to write the law (listing criteria), be the judge and enforce rulings on videos, posts etc. Using a Generalized TCR instead, allows these powers to be moved to the edges, such that the users of the app get to write the listing criteria and pick an arbitrator they consider to be neutral. Enforcing is done by the blockchain. ## Quick Start Kleros provides an SDK to ease integration: ```shell npm add @kleros/gtcr-sdk ``` > Note: The terms TCR, GTCR and list are used interchangeably here and refer to the same thing: a Generalized TCR contract. Example: ### Fetching deployed lists. Curate uses a factory contract to deploy and keep track of TCRs. To fetch a list of addresses of GTCRs you just have to provide the factory address: ```typescript // The GTCR factory contract on mainnet is located at: 0xe9dd523600b74b8ef0af164687079a6c437f9cd5 import { GTCRFactory } from "@kleros/gtcr-sdk"; (async () => { const gtcrFactory = new GTCRFactory( window.ethereum, "0xe9dd523600b74b8ef0af164687079a6c437f9cd5" ); await gtcrFactory.getTCRAddresses(); })(); ``` You can find a react example at > Note: Curate factory deploys 2 contracts per list created: One is the list itself and another is the badges TCR. This second list is a list of lists used to connect TCRs together. ### Fetching an Item To get information on a single item, use the `getItem` function of the `GeneralizedTCR` class: ```typescript import { GTCRFactory } from "@kleros/gtcr-sdk"; // This example assumes you have an injected provider // (e.g. Metamask) set to mainnet. const GTCR_VIEW_ADDRESS = "0x98f1309f96044000174a89c2a0e2001ea5d7a524"; const IPFS_GATEWAY = "https://cdn.kleros.link"; const LIST_ADDRESS = "0x99A0f0e0d9Ee776D791D2E55c215d05ccF7286fC"; // List of stories for the kleros storytelling program. const DEPLOYMENT_BLOCK = 10247266; // Optional, but recommended. Setting the deployment block speeds up requests. const ITEM_ID = "0x22a0a12e2c9ac41b15b5c3bc4aab748550663f164f64316e0ff9447b336e3565"; (async () => { const gtcr = new GeneralizedTCR( window.ethereum, LIST_ADDRESS, GTCR_VIEW_ADDRESS, IPFS_GATEWAY, DEPLOYMENT_BLOCK ); const item = await gtcr.getItem(ITEM_ID) console.info(item.decodedData) // Outputs the item column values. })(); ``` You can find a react example at ### Fetching Items You can fetch items from a list using the `getItems` method of the `GeneralizedTCR` class. This will return an array of items with the latest request information: ```typescript import { GTCRFactory } from "@kleros/gtcr-sdk"; // This example assumes you have an injected provider // (e.g. Metamask) set to mainnet. const GTCR_VIEW_ADDRESS = "0x98f1309f96044000174a89c2a0e2001ea5d7a524"; const IPFS_GATEWAY = "https://cdn.kleros.link"; const LIST_ADDRESS = "0x99A0f0e0d9Ee776D791D2E55c215d05ccF7286fC"; // List of stories for the kleros storytelling program. const DEPLOYMENT_BLOCK = 10247266; // Optional, but recommended. Setting the deployment block speeds up requests. (async () => { const gtcr = new GeneralizedTCR( window.ethereum, LIST_ADDRESS, GTCR_VIEW_ADDRESS, IPFS_GATEWAY, DEPLOYMENT_BLOCK ); const items = (await gtcr.getItems()) console.info(items.map(item => item.decodedData)) // Outputs the item column values. })(); ``` You can find a React example at: ### Fetching Meta Evidence and Metadata The address of a GTCR by itself is not very useful for building, UIs. Usually we need other information such as the list name, description, logo etc. This data is stored inside the `metadata` field inside the meta evidence file. You can use the `getLatestMetaEvidence` to get the file like so: ```typescript const gtcr = new GeneralizedTCR( window.ethereum, LIST_ADDRESS, GTCR_VIEW_ADDRESS, IPFS_GATEWAY, DEPLOYMENT_BLOCK ); const [registrationMetaEvidence, removalMetaEvidence] = (await gtcr.getLatestMetaEvidence()) // Both removal and registration meta evidence contain the same `metadata`. console.info(registrationMetaEvidence.metadata) // Outputs { tcrTitle: string // The list title. tcrDescription: string // The list description. columns: Column[] // Used by @kleros/gtcr-encoder itemName: string // The noun used when building UIs. E.g. "Token" for a list of tokens -> generates "Submit *token*", "Challenge token", etc. itemNamePlural: string // Plural version of `itemName`. logoURI: string // Link to the list logo. Usually an IPFS URI. requireRemovalEvidence: boolean // Whether to require evidence when removing an item. isTCRofTCRs: boolean // Whether this is a list of GTCR addresses. relTcrDisabled: boolean // Whether the badges TCR is enabled. } ``` > For more information on meta evidence files, see [EIP-792](https://github.com/ethereum/EIPs/issues/792) and [erc-792 docs](https://developer.kleros.io/en/latest/)introduction.html. # Light Curate: Integration for Devs Since Curate was first conceptualized, demand for ethereum block space has skyrocketed. This put a high price floor on the usecases that Curate can be with. Furthermore, we learned that there are is a lot more demand for user facing data than for contract to contract queries. Light Curate is a new version of the contract that significantly decreases costs of deployment and operation of Curate lists by leveraging new technologies and changing the strategy for data storage. 1- Light Curate does not use contract storage to store item data. Instead, we only store the item's IPFS multihash in the contract. This means other contracts can't query the TCR with field values, but storage costs are roughly O(1) vs Classic Curate's O(n). 2- The Graph `ipfs` api means we can also store the item fields in the subgraph. This comes with several benefits, among them: - No need to use `@kleros/gtcr-encoder` to encode and decode items. Just query the subgraph and you have the item. - Faster, scalable search: Classic Curate needs to sync with the client by downloading every single item and decoding it. With subgraphs we do not need to do this and can query the fields directly. - New need for complex solidity code searching fields on-chain. 3- EIP-1167: Light Curate uses the minimal proxy for new deployments. This means the cost of deploying a new TCR dropped from roughly 7 million gas to 700k. Ten times cheaper! ## Development This section will be divided into 3 sections: 1- Fetching Parameters: Your UI needs to display some important information to the users such as, what is the bounty for successfuly challenges and how long do items stay in the challenge period. 1- Item Submission: Here you will learn how to build a button to submit an item to the UI. 2- Fetching Items: How to view items and item details. 3- Item Interaction: This includes challenging, submitting evidence and crowdfunding appeals. ### Fetching Parameters We use a view contract to fetch all the relevant information at once. Deployments: * Gnosis: `0x08e58Bc26CFB0d346bABD253A1799866F269805a` ([source](https://github.com/kleros/gtcr-subgraph/blob/master/networks.json)) > Note: If you are using react, you can take the hook we built [here](https://github.com/kleros/gtcr/blob/5e313ced24f5e3fc3a54f812e07fb1f86a6b2621/src/hooks/tcr-view.js) or use it as an example. ### Item Submission. With light Curate, item submission consists of first uploading the item to IPFS and then submitting a transaction with the required deposit. Since we use `@graphprotocol/graph-ts` we must submit items to its ipfs endpoint until they allow custom endpoints. In addition, we also upload to kleros ipfs node. > In addition to Kleros' and The Graph's, we strongly advise pin the data to ipfs nodes you control as well. Update the provided below for this. Full example [here](https://github.com/kleros/gtcr/blob/5e313ced24f5e3fc3a54f812e07fb1f86a6b2621/src/utils/ipfs-publish.js) ```bash REACT_APP_IPFS_GATEWAY=https://cdn.kleros.link REACT_APP_HOSTED_GRAPH_IPFS_ENDPOINT=https://api.thegraph.com/ipfs ``` #### Upload and Transaction ```typescript const pinFiles = async ( data: FormData, pinToGraph: boolean ): Promise< [Array, Array<{ filebaseCid: string; graphCid: string }>] > => { const cids = new Array(); // keep track in case some cids are inconsistent const inconsistentCids = new Array<{ filebaseCid: string; graphCid: string; }>(); for (const [_, dataElement] of Object.entries(data)) { if (dataElement.isFile) { const { filename, mimeType, content } = dataElement; const path = `${filename}`; const cid = await filebase.storeDirectory([ new File([content], path, { type: mimeType }), ]); if (pinToGraph) { const graphResult = await publishToGraph(filename, content); if (!areCidsConsistent(cid, graphResult)) { console.warn("Inconsistent cids from Filebase and Graph Node :", { filebaseCid: cid, graphCid: graphResult[1].hash, }); inconsistentCids.push({ filebaseCid: cid, graphCid: graphResult[1].hash, }); } } cids.push(`/ipfs/${cid}/${path}`); } } return [cids, inconsistentCids]; }; /** * Send file to IPFS network via The Graph hosted IPFS node * @param data - The raw data from the file to upload. * @returns ipfs response. Should include the hash and path of the stored item. */ export const publishToGraph = async (fileName, data) => { const url = `${process.env.GRAPH_IPFS_ENDPOINT}/api/v0/add?wrap-with-directory=true`; const payload = new FormData(); payload.append("file", new Blob([data]), fileName); const response = await fetch(url, { method: "POST", body: payload, }); if (!response.ok) { throw new Error( `HTTP error! status: ${response.status}, Failed to pin to graph` ); } const result = parseNewlineSeparatedJSON(await response.text()); return result.map(({ Name, Hash }) => ({ hash: Hash, path: `/${Name}`, })); }; /** * @description parses json from stringified json's separated by new line */ const parseNewlineSeparatedJSON = (text) => { const lines = text.trim().split("\n"); return lines.map((line) => JSON.parse(line)); }; export const areCidsConsistent = (filebaseCid, graphResult) => { const graphCid = graphResult[1].hash; return graphCid === filebaseCid; }; ``` The JSON file for the object is composed of its metadata and fields. * Metadata (columns): An array describing each of the items columns (what's its type, name, description, etc.) * Values (values): An object mapping the column name to the value. The metadata is available inside the meta evidence file, which is returned by the useTCRView hook. The values are input by the user. Example of columns used by the TCR at ```json [ { "label": "Logo", "description": "The token's logo.", "type": "image", "isIdentifier": false }, { "label": "Name", "description": "The token name.", "type": "text", "isIdentifier": true }, { "label": "Ticker", "description": "The token ticker.", "type": "text", "isIdentifier": true }, { "label": "Address", "description": "The token address.", "type": "address", "isIdentifier": true }, { "label": "Chain ID", "description": "The ID of the chain the token contract was deployed", "type": "number" }, { "label": "Decimals", "description": "The number of decimal places.", "type": "number" } ] ``` And an example of values. Note that it is required for the keys to match the column names in the columns object. ```json { "Logo": "/ipfs/QmT4vij3PrGZEQ1zarTrPmkqQWggRQN6VEpewSHJXbkeXh/pnk-logo.png", "Name": "Pinakion", "Ticker": "PNK", "Address": "0x93ED3FBe21207Ec2E8f2d3c3de6e058Cb73Bc04d", "Chain ID": "1", "Decimals": "18" } ``` With this in hand we can submit the item. ```typescript const gtcr = new ethers.Contract(tcrAddress, _gtcr, signer) const enc = new TextEncoder() const fileData = enc.encode(JSON.stringify({ columns, values })) const ipfsEvidencePath = await ipfsPublish('item.json', fileData) // Request signature and submit. const tx = await gtcr.addItem(ipfsEvidencePath, { value: submissionDeposit }) ``` ### Fetching Items > We break down this section into two as list views and details view have different requirements. Fetching items is best done via the subgraph we provide. If you deployed a list using the factory, it already has a subgraph deployed and available [here](https://thegraph.com/explorer/subgraphs/9hHo5MpjpC1JqfD3BsgFnojGurXRHTrHWcUcZPPCo6m8?view=Query\&chain=arbitrum-one). #### List Whenever we want to fetch items, or a specific item, we must pass the TCR address to the subgraph. See [this react example](https://github.com/kleros/gtcr/blob/7995e3de0a740dc1056a03a68a34185ac71d8909/src/utils/graphql/light-items.js#L29-L37) for more details. A standard query for the first page of a given list, ordered by the most recent requests, looks like this. ```typescript const ITEMS_PER_PAGE = 40 const orderDirection = 'asc' const page = 1 const itemsWhere = `{ registry: "${tcrAddress.toLowerCase()}" }` const GTCR_SUBGRAPH_URL=`https://gateway-arbitrum.network.thegraph.com/api/${YOUR_API_KEY}/subgraphs/id/9hHo5MpjpC1JqfD3BsgFnojGurXRHTrHWcUcZPPCo6m8` // You need to replace with your API key const query = { query: ` { items( skip: ${(Number(page) - 1) * ITEMS_PER_PAGE} first: ${ITEMS_PER_PAGE} orderDirection: ${orderDirection} orderBy: latestRequestSubmissionTime where: ${itemsWhere} ) { itemID status data metadata{ props { value } } requests(first: 1, orderBy: submissionTime, orderDirection: desc) { disputed disputeID submissionTime resolved requester challenger resolutionTime rounds(first: 1, orderBy: creationTime, orderDirection: desc) { appealPeriodStart appealPeriodEnd ruling hasPaidRequester hasPaidChallenger amountPaidRequester amountPaidChallenger } } } } ` } const { data, errors } = await ( await fetch(GTCR_SUBGRAPH_URL, { method: 'POST', headers: { 'Content-Type': "application/json", }, body: JSON.stringify(query) }) ).json() ``` #### Details If you want, you can also use apollo to cache queries and make the app load faster. ```typescript const ITEM_DETAILS_QUERY = gql` query itemDetailsQuery($id: String!) { item(id: $id) { data requests(orderBy: submissionTime, orderDirection: desc) { requestType disputed disputeID submissionTime resolved requester arbitrator challenger evidenceGroupID creationTx resolutionTx rounds(orderBy: creationTime, orderDirection: desc) { appealPeriodStart appealPeriodEnd ruling hasPaidRequester hasPaidChallenger amountPaidRequester amountPaidChallenger } } } } ` // subgraph item entities have id "@" const compoundId = `${itemID}@${tcrAddress.toLowerCase()}` const detailsViewQuery = useQuery(ITEM_DETAILS_QUERY, { variables: { id: compoundId } }) ``` ### Item Interaction This is the easiest part of the application. All items are referenced by their ID which is the keccak256 hash of the IPFS URI. With it you can: * Execute requests: This is for when a request passed the challenge period without any challenges. * Challenge requests (registration or removal) via the contract's `challengeRequest` function * Submit evidence: `submitEvidence` by passing the evidence json file following (ERC-1497)\[] standard. * Fund appeals: `fundAppeal` # Guide for Preparing Transactions ### How To: createSubcourt * When a request comes in to create a new subcourt, start by checking the final Snapshot voting results to see the parameters of the new court. * Example * To prepare the transaction itself, head over to the respective block explorer of the court deployment. * See links to contract deployments here [Deployment Addresses](/developer/deployment-addresses) * Then connect your wallet and navigate to the write contract section of the block explorer.
* Fill in the parameters of the createSubcourt function like so 👇
* Before writing to the contract, make sure your wallet is connected to the network of the deployment you’re trying to write to. In the example above, we’ll need to be connected to Gnosis Chain. **Note:** It’s best practice to take a screenshot of the input parameters so that whoever executes the transaction can double check. * Click on Write and navigate to the hex section on your wallet. From there, copy the raw transaction data and paste it somewhere safe.
### How To: PolicyRegistry * The first step of preparing a PolicyRegistry transaction is writing and pinning the policy JSON. To make this easy, we use the file-to-ipfs package. ```shell mkdir policy // cd policy // yarn init -y // npm i @kleros/file-to-ipfs ``` * Create a json file and write the policy according to what was specified in the snapshot proposal. ```json { "name": "xDai Solidity Court", "description": "**Court purpose** \n\n If the disputed code is of significant size (> 500 code lines), parties in the dispute should point out specific parts of the content which are being disputed. Otherwise, jurors should refuse to arbitrate.", "summary": "", "requiredSkills": "This court requires a good level of solidity. Jurors who are not solidity intermediate developers are advised to stake into this court only if they also know how to make relatively simple contracts, know the main solidity hacks and can compute the complexity of simple functions." } ``` * In the index.js file, run the following script to pin whichever policies you’ve written. ```javascript const ftIpfs = require("@kleros/file-to-ipfs"); async function pinSol() { const solPath = await ftIpfs("./files/xDai-Solidity-Court-Policy.json"); console.log(`Solidity Court: ${solPath}`); } async function pinJs() { const jsPath = await ftIpfs("./files/xDai-Javascript-Court-Policy.json"); console.log(`Javascript Court: ${jsPath}`); } async function pinDev() { const devPath = await ftIpfs("./files/xDai-Development-Court-Policy.json"); console.log(`Development Court: ${devPath}`); } async function main() { pinSol(); pinJs(); pinDev(); } main(); /* Output Development Court: /ipfs/QmbgUL2iv9XH3jui7xdLBXp2Hqe4VqGnNkK7PnAorJ8XQa/xDai-Development-Court-Policy.json Solidity Court: /ipfs/QmQbyk1qnD4e4MQrwSr6a21w2t82YJEMxU3F7QTYKkxuNS/xDai-Solidity-Court-Policy.json Javascript Court: /ipfs/Qme15AUfpvLX3iwEtqswe26PQHMmKnF4eWGywBPqbkdqcD/xDai-Javascript-Court-Policy.json */ ``` * Copy + Paste the output somewhere safe before closing terminal. * Go to the PolicyRegistry deployment [Deployment Addresses](/developer/deployment-addresses) * Write the inputs into the setPolicy function (subcourtID and URI string).
* Follow the same steps outlined in the createSubcourt guide to get the raw transaction data. ### Presenting Transactions: * Make a copy of this [template](https://docs.google.com/document/d/1av-IU5aKwRFzKhktdVNAlkt12sozows6uBapj1T-lq8/edit?usp=sharing) and fill in the necessary informaton. * If submitting through **Discord** tag @xpriment626 and share the link to your doc. * If submitting through **Telegram** tag @clesaege and share the link to your doc. * If submitting through **Slack** share the link to your doc on the public #dev channel. # Overview Welcome to the contribution guide for all software pertaining to Kleros. ## How to contribute? The purpose of these guidelines is to serve as a living contribution and collaboration guide for all our projects. Everyone, not just Kleros team members, is welcome to participate in its writing and editing. We are always looking to enhance and improve our processes so we can decentralize justice faster! ## Table of Contents This guide is a compilation of years of experience in the fields of traditional software engineering, and smart contract and financial software auditing. We've broken it down into three parts: | General Workflow | Smart Contract Workflow | Code Style & Guidelines | License & Code of Conduct | | --------------------------------------------------------------- | ------------------------------------------- | ------------------------------------------------------ | -------------------------------------------- | | General process and standards for writing and pushing software. | Smart contract specific security protocols. | Stylistic guidelines for our main languages and tools. | Our standard license and conduct guidelines. | ## Kathari CLI \[Deprecated] ~~To make following our standards easier, we made~~ [~~Kathari~~](https://github.com/kleros/kathari)~~, a linting and formatting scripts for multiple types of projects.~~ {% hint style="info" %} ~~Kathari means "Clean" in Greek.~~ {% endhint %} ~~It's a CLI that can easily be integrated into new projects to provide automatic linting and formatting that adheres to our standards on everything from code to git commit messages.~~ ~~It's based on very popular open source technologies so there are integrations for all of the most popular text editors and IDEs.~~ ## Main Repos * [kleros](https://github.com/kleros) - [Kleros whitepaper](https://kleros.io/assets/whitepaper.pdf) arbitrator implementation smart contracts. * [kleros-interaction](https://github.com/kleros-interaction) - Arbitrable smart contracts and other contracts that can interact with Kleros. * [archon](https://github.com/kleros/archon) - Wrapper that simplifies interfacing with smart contracts that adhere to the [arbitration (ERC792)](https://github.com/ethereum/EIPs/issues/792) and [evidence (ERC1497)](https://github.com/ethereum/EIPs/issues/1497) standards. ## Referencing This Guide All of our projects' `CONTRIBUTING.md` files should link to this page, but they can also specify their own project-specific guidelines in that same file. {% hint style="info" %} This site is maintained at [github.com/kleros/CONTRIBUTING.md](https://github.com/kleros/CONTRIBUTING.md) and hosted at [contributing.kleros.io](https://contributing.kleros.io)! {% endhint %} The rules in this guide are meant to be followed as much as possible, but should not override common sense. > The golden rule is that there are no golden rules. > > -George Bernard Shaw- # General Dev. Workflow How we keep track of new development work and push new code. {% content-ref url="/pages/-LPbRSvj2qp1j0-gfGX3" %} [Task Tracking & Lifecycle](/contribution-guidelines/general-dev.-workflow/task-tracking-and-lifecycle) {% endcontent-ref %} {% content-ref url="/pages/-LPbRnOvNLHG3jY4\_HA1" %} [Releases](/contribution-guidelines/general-dev.-workflow/releases) {% endcontent-ref %} --- [Next Page](/llms-full.txt/1)