Skip to content

Commit c76e4af

Browse files
jaybuidljaybuidl
committed
docs: specifications
1 parent 9b77f32 commit c76e4af

8 files changed

+2599
-0
lines changed

‎contracts/specifications/arbitrable.md

+333
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,333 @@
1+
# 🤝 Arbitrable V2
2+
3+
## 📋 Overview
4+
5+
The Arbitrable interface (`IArbitrableV2`) and its reference implementation (`DisputeResolver`) are key components of the Kleros V2 protocol that enable contracts to create and handle disputes. The Arbitrable pattern allows any contract to request arbitration from a Kleros court while maintaining flexibility in how they handle rulings.
6+
7+
## 📑 Table of Contents
8+
9+
1. [🔍 Interface Specification](#-interface-specification)
10+
- [Events](#events)
11+
- [Core Methods](#core-methods)
12+
2. [📝 DisputeResolver Implementation](#-disputeresolver-implementation)
13+
- [Dispute Creation](#dispute-creation)
14+
- [Ruling Handling](#ruling-handling)
15+
- [Dispute Templates](#dispute-templates)
16+
3. [🔄 Interactions](#-interactions)
17+
- [Dispute Creation Flow](#dispute-creation-flow)
18+
- [Ruling Flow](#ruling-flow)
19+
20+
## 🔍 Interface Specification
21+
22+
The `IArbitrableV2` interface defines the minimum requirements for a contract to interact with Kleros courts. It specifies how disputes are created and how rulings are received.
23+
24+
### Events
25+
26+
The interface defines two key events that enable tracking of dispute lifecycle and rulings:
27+
28+
#### DisputeRequest
29+
30+
```solidity
31+
event DisputeRequest(
32+
IArbitratorV2 indexed _arbitrator,
33+
uint256 indexed _arbitratorDisputeID,
34+
uint256 _externalDisputeID,
35+
uint256 _templateId,
36+
string _templateUri
37+
);
38+
```
39+
40+
Emitted when a new dispute is created. This event serves two critical purposes:
41+
42+
1. Links the dispute to its evidence template
43+
2. Provides traceability between different dispute identifiers
44+
45+
Parameters:
46+
47+
- `_arbitrator`: The Kleros court contract that will arbitrate the dispute
48+
- `_arbitratorDisputeID`: The unique identifier of the dispute in the arbitrator's contract
49+
- `_externalDisputeID`: A local identifier for the dispute in the arbitrable contract, allowing correlation between arbitrator and arbitrable dispute IDs
50+
- `_templateId`: The identifier of the dispute template in the template registry (mutually exclusive with `_templateUri`)
51+
- `_templateUri`: Direct URI to the dispute template, e.g., IPFS path '/ipfs/...' (mutually exclusive with `_templateId`)
52+
53+
Note: Either `_templateId` or `_templateUri` should be used, but not both. This flexibility allows for both on-chain template registry and direct template URI references.
54+
55+
#### Ruling
56+
57+
```solidity
58+
event Ruling(IArbitratorV2 indexed _arbitrator, uint256 indexed _disputeID, uint256 _ruling);
59+
```
60+
61+
Emitted when the arbitrator gives a ruling on a dispute. This event must be emitted by the arbitrable contract when it receives and processes a ruling.
62+
63+
Parameters:
64+
65+
- `_arbitrator`: The Kleros court contract that made the ruling (indexed for efficient filtering)
66+
- `_disputeID`: The identifier of the dispute in the arbitrator's contract (indexed for efficient filtering)
67+
- `_ruling`: The ruling value given by the arbitrators where:
68+
- `0`: Indicates "Refused to rule" or "Unable to rule"
69+
- `1` to `numberOfChoices`: The actual ruling value corresponding to the dispute's choices
70+
71+
Note: The ruling value's meaning is dispute-specific and should be interpreted according to the dispute's context and template.
72+
73+
### Dispute Templates
74+
75+
The DisputeResolver uses a structured template system to provide clear information about disputes to jurors. Templates are either stored in the template registry or referenced directly via URI.
76+
77+
#### Template Structure
78+
79+
A dispute template is a JSON document with the following structure:
80+
81+
```json
82+
{
83+
"title": "string", // Clear, concise title of the dispute
84+
"description": "string", // Detailed description of the case
85+
"question": "string", // The specific question jurors must answer
86+
"category": "string", // The type/category of dispute
87+
"answers": [
88+
// Possible rulings jurors can choose from
89+
{
90+
"title": "string", // Short answer (e.g., "Yes", "No")
91+
"id": "string", // Unique identifier (e.g., "0x1")
92+
"description": "string" // Detailed explanation of this choice
93+
}
94+
],
95+
"version": "string", // Template format version
96+
"policyURI": "string", // Link to applicable policy document
97+
"arbitratorAddress": "string", // Address of the Kleros court
98+
"arbitratorChainID": "string" // Chain ID where the court exists
99+
}
100+
```
101+
102+
#### Example Template
103+
104+
Here's an example of a dispute template for a residential lease dispute:
105+
106+
```json
107+
{
108+
"title": "Ms. Jamie Zachreson v. Mr. Craig Veale: Appeal of Prior Decision",
109+
"description": "Appeal of a residential lease dispute regarding lease violation and rent refund...",
110+
"question": "Did Mr. Craig Veale violate the terms of the lease agreement in a way that justified Ms. Jamie Zachreson terminating the tenancy and withholding the rent and deposit?",
111+
"category": "Residential lease",
112+
"answers": [
113+
{
114+
"title": "Yes",
115+
"id": "0x1",
116+
"description": "In favor of Ms. Jamie Zachreson: The lease included a valid and enforceable clause..."
117+
},
118+
{
119+
"title": "No",
120+
"id": "0x2",
121+
"description": "In favor of Mr. Craig Veale: The lease did not include the disputed clause..."
122+
},
123+
{
124+
"title": "Partially",
125+
"id": "0x3",
126+
"description": "Split Responsibility: Return partial payment..."
127+
},
128+
{
129+
"title": "Not enough evidence",
130+
"id": "0x4",
131+
"description": "Insufficient evidence to determine..."
132+
},
133+
{
134+
"title": "Refuse to arbitrate",
135+
"id": "0x5",
136+
"description": "Case ineligible for arbitration..."
137+
}
138+
],
139+
"version": "1.0",
140+
"policyURI": "/ipfs/QmcDrvCaXtae4o6KgXYhi4yLKm5JYQSRQdZ9itbnASbsb9",
141+
"arbitratorAddress": "0x991d2df165670b9cac3B022f4B68D65b664222ea",
142+
"arbitratorChainID": "42161"
143+
}
144+
```
145+
146+
Key aspects of templates:
147+
148+
- The `answers` array corresponds to valid ruling values (1 to N)
149+
- Each answer must have a clear title and detailed description
150+
- The `question` should be specific and answerable based on the options
151+
- Templates can be stored:
152+
1. On-chain in the template registry (referenced by `templateId`)
153+
2. Off-chain (referenced by `templateUri`, typically IPFS)
154+
- The number of answers must match `numberOfRulingOptions` in the dispute creation
155+
156+
### Core Methods
157+
158+
```solidity
159+
function rule(uint256 _disputeID, uint256 _ruling) external;
160+
```
161+
162+
- Called by the arbitrator to give a ruling
163+
- Must verify caller is the arbitrator
164+
- `_ruling` of 0 is reserved for "Unable/unwilling to make a decision"
165+
166+
## 📝 DisputeResolver Implementation
167+
168+
The `DisputeResolver` contract provides a reference implementation of `IArbitrableV2` that can be used directly or as a base for more complex arbitrable contracts.
169+
170+
### Dispute Creation
171+
172+
Two methods for creating disputes:
173+
174+
1. **Template-based Creation**:
175+
176+
```solidity
177+
function createDisputeForTemplate(
178+
bytes calldata _arbitratorExtraData,
179+
string calldata _disputeTemplate,
180+
string memory _disputeTemplateDataMappings,
181+
uint256 _numberOfRulingOptions
182+
) external payable returns (uint256 disputeID)
183+
```
184+
185+
2. **URI-based Creation**:
186+
187+
```solidity
188+
function createDisputeForTemplateUri(
189+
bytes calldata _arbitratorExtraData,
190+
string calldata _disputeTemplateUri,
191+
uint256 _numberOfRulingOptions
192+
) external payable returns (uint256 disputeID)
193+
```
194+
195+
Key aspects:
196+
197+
- Both methods require arbitration fees to be sent with the call
198+
- At least 2 ruling options must be specified
199+
- Creates both local and arbitrator-side dispute records
200+
- Emits `DisputeRequest` with template information
201+
202+
### Ruling Handling
203+
204+
The `rule` function implementation:
205+
206+
- Verifies the caller is the arbitrator
207+
- Maps arbitrator dispute ID to local ID
208+
- Validates the ruling is within allowed options
209+
- Prevents duplicate rulings
210+
- Updates dispute state and emits `Ruling` event
211+
212+
## 🔄 Interactions
213+
214+
### Dispute Creation Flow
215+
216+
```mermaid
217+
sequenceDiagram
218+
participant User
219+
participant DisputeResolver
220+
participant Arbitrator
221+
participant TemplateRegistry
222+
223+
User->>DisputeResolver: createDisputeForTemplate()
224+
activate DisputeResolver
225+
Note over DisputeResolver: Validate parameters
226+
DisputeResolver->>Arbitrator: createDispute()
227+
Arbitrator-->>DisputeResolver: Return disputeID
228+
DisputeResolver->>TemplateRegistry: setDisputeTemplate()
229+
TemplateRegistry-->>DisputeResolver: Return templateId
230+
DisputeResolver-->>User: Return arbitratorDisputeID
231+
deactivate DisputeResolver
232+
DisputeResolver->>DisputeResolver: Emit DisputeRequest
233+
```
234+
235+
### Ruling Flow
236+
237+
```mermaid
238+
sequenceDiagram
239+
participant Arbitrator
240+
participant DisputeResolver
241+
participant Listeners
242+
243+
Arbitrator->>DisputeResolver: rule(disputeID, ruling)
244+
activate DisputeResolver
245+
Note over DisputeResolver: Validate caller & ruling
246+
DisputeResolver->>DisputeResolver: Map to local dispute
247+
DisputeResolver->>DisputeResolver: Update dispute state
248+
DisputeResolver->>Listeners: Emit Ruling
249+
deactivate DisputeResolver
250+
```
251+
252+
The DisputeResolver provides a foundation for creating arbitrable contracts in the Kleros ecosystem. It handles the core functionality of dispute creation and ruling management while allowing derived contracts to add custom business logic.
253+
254+
### Dispute Templates
255+
256+
**:warning: TODO: add the generic specification for Dispute Templates and Mappings**
257+
258+
#### Template Structure
259+
260+
**:warning: THIS TEMPLATE DOES NOT LOOK COMPLIANT WITH THE SDK SCHEMA**
261+
262+
```json
263+
{
264+
"title": "string", // Clear, concise title of the dispute
265+
"description": "string", // Detailed description of the case
266+
"question": "string", // The specific question jurors must answer
267+
"category": "string", // The type/category of dispute
268+
"answers": [
269+
// Possible rulings jurors can choose from
270+
{
271+
"title": "string", // Short answer (e.g., "Yes", "No")
272+
"id": "string", // Unique identifier (e.g., "0x1")
273+
"description": "string" // Detailed explanation of this choice
274+
}
275+
],
276+
"version": "string", // Template format version
277+
"policyURI": "string", // Link to applicable policy document
278+
"arbitratorAddress": "string", // Address of the Kleros court
279+
"arbitratorChainID": "string" // Chain ID where the court exists
280+
}
281+
```
282+
283+
#### Example Template
284+
285+
```json
286+
{
287+
"title": "Ms. Jamie Zachreson v. Mr. Craig Veale: Appeal of Prior Decision",
288+
"description": "Appeal of a residential lease dispute regarding lease violation and rent refund...",
289+
"question": "Did Mr. Craig Veale violate the terms of the lease agreement in a way that justified Ms. Jamie Zachreson terminating the tenancy and withholding the rent and deposit?",
290+
"category": "Residential lease",
291+
"answers": [
292+
{
293+
"title": "Yes",
294+
"id": "0x1",
295+
"description": "In favor of Ms. Jamie Zachreson: The lease included a valid and enforceable clause..."
296+
},
297+
{
298+
"title": "No",
299+
"id": "0x2",
300+
"description": "In favor of Mr. Craig Veale: The lease did not include the disputed clause..."
301+
},
302+
{
303+
"title": "Partially",
304+
"id": "0x3",
305+
"description": "Split Responsibility: Return partial payment..."
306+
},
307+
{
308+
"title": "Not enough evidence",
309+
"id": "0x4",
310+
"description": "Insufficient evidence to determine..."
311+
},
312+
{
313+
"title": "Refuse to arbitrate",
314+
"id": "0x5",
315+
"description": "Case ineligible for arbitration..."
316+
}
317+
],
318+
"version": "1.0",
319+
"policyURI": "/ipfs/QmcDrvCaXtae4o6KgXYhi4yLKm5JYQSRQdZ9itbnASbsb9",
320+
"arbitratorAddress": "0x991d2df165670b9cac3B022f4B68D65b664222ea",
321+
"arbitratorChainID": "42161"
322+
}
323+
```
324+
325+
Key aspects of templates:
326+
327+
- The `answers` array corresponds to valid ruling values (1 to N)
328+
- Each answer must have a clear title and detailed description
329+
- The `question` should be specific and answerable based on the options
330+
- Templates can be stored:
331+
1. On-chain in the template registry (referenced by `templateId`)
332+
2. Off-chain (referenced by `templateUri`, typically IPFS)
333+
- The number of answers must match `numberOfRulingOptions` in the dispute creation

0 commit comments

Comments
 (0)