Skip to content

Commit

Permalink
Update README
Browse files Browse the repository at this point in the history
  • Loading branch information
@shleikes
shleikes committed Apr 1, 2024
1 parent 9f181d3 commit 2bacbf6
Showing 1 changed file with 43 additions and 38 deletions.
81 changes: 43 additions & 38 deletions x/conflict/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,33 +6,35 @@ This document specifies the conflict module of Lava Protocol.

The purpose of the conflict module is to ensure data reliability from providers that offer their services on Lava. To achieve this, Lava allows consumers to report mismatches between different responses to the same request (for deterministic APIs). This way, Lava can identify fraudulent providers and penalize them by confiscating their staked tokens. Consumers are incentivized to do so by Lava, as they receive tokens taken from the fraudulent provider being punished.


## Contents
* [Concepts](#concepts)
* [Response Conflict](#response-conflict)
* [Finalization Conflict](#finalization-conflict)
* [Self Provider Conflict](#self-provider-conflict)
* [Commit Period](#commit-period)
* [Reveal Period](#reveal-period)
* [Conflict Resolve](#Conflict-Resolve)
* [Parameters](#parameters)
* [Queries](#queries)
* [Transactions](#transactions)
* [Events](#events)

- [Concepts](#concepts)
- [Response Conflict](#response-conflict)
- [Finalization Conflict](#finalization-conflict)
- [Self Provider Conflict](#self-provider-conflict)
- [Commit Period](#commit-period)
- [Reveal Period](#reveal-period)
- [Conflict Resolve](#Conflict-Resolve)
- [Parameters](#parameters)
- [Queries](#queries)
- [Transactions](#transactions)
- [Events](#events)

## Concepts

### Response Conflict

A response conflict occurs when a consumer receives mismatched responses from different providers. In such cases, the consumer is eligible to send a conflict detection message (this is done randomly, determined by the spec reliability threshold field), which includes the relay request and responses from the two providers. This conflict detection message is then validated to ensure that the responses are different, the signatures match the providers and consumer, and that the API is deterministic. If the message is valid, a conflict is opened.

A group of validators is selected as a jury to determine the fraudulent and honest providers. Through an event, the chain announces the conflict voting period and the participating providers. During the voting period, providers need to submit their hashed response + salt to the original relay request. This is done to prevent other providers from cheating or copying their vote. Once the voting period ends, the conflict moves to the reveal state. In this state, providers need to reveal their response + salt, which is then verified and compared to the original responses. After the reveal period ends, the votes are counted, and the provider with the fewest votes, and the jury that voted for him, are penalized by having a fraction of their staked tokens taken and distributed among all the other participants.

### Finalization Conflict
N/A

A finalization conflict occurs when a consumer receives mismatched finalized block hashes from different providers. This is similar to a response conflict, except it involves the finalized block hash instead of a response to a request. The process is identical - the consumer submits a conflict detection message, a jury is selected, providers commit/reveal votes, and the provider with the fewest votes is penalized.

### Self Provider Conflict
N/A

A finalization conflict occurs when a consumer receives mismatched finalized block hashes from the same provider. This can happen if a provider responds with different finalized block hashes to the same request sent multiple times. In this case, no voting is needed, since the provider contradicted itself. The provider is directly penalized for providing inconsistent responses.

### Commit Period

Expand Down Expand Up @@ -68,7 +70,7 @@ To resolve the conflict, a majority of votes must be in favor of Provider A, Pro

Once a majority is reached, providers who voted for the wrong side of the conflict will be slashed and frozen, and the slashed amount will be added to the conflict reward pool. The reward pool is then distributed between the consumer and the providers who voted for the correct provider.
Providers in the jury that did not vote are punished by jail and slashing, their slashed amount will be added to the conflict reward pool.
For the conflict resolution there needs to be a majority met of votes for Provider A, Provider B or None of them.
For the conflict resolution there needs to be a majority met of votes for Provider A, Provider B or None of them.
If a majority was not met, conflict reward pool is given to the consumer that reported the conflict.
Once a majority is met providers that voted to the wrong side of the conflict are slashed and frozen, the slashed amount is added to the conflict reward pool.
Now the reward pool is distributed between the comsumer and the providers that voted for the correct provider.
Expand All @@ -77,18 +79,18 @@ Now the reward pool is distributed between the comsumer and the providers that v

The conflict module contains the following parameters:

| Key | Type | Default Value |
| -------------------------------------- | ----------------------- | -----------------|
| MajorityPercent | math.LegacyDec | 0.95 |
| VoteStartSpan | uint64 | 3 |
| VotePeriod | uint64 | 2 |
| Rewards | rewards | N/A |
| Key | Type | Default Value |
| --------------- | -------------- | ------------- |
| MajorityPercent | math.LegacyDec | 0.95 |
| VoteStartSpan | uint64 | 3 |
| VotePeriod | uint64 | 2 |
| Rewards | rewards | N/A |

`MajorityPercent` determines the majority needed to conclude who is the winner of the conflict.
`MajorityPercent` determines the majority needed to conclude who is the winner of the conflict.

`VoteStartSpan` is the amount of epochs in the past that a consumer can send conflict detection message for.

`VotePeriod` is the number of epochs in the past that a consumer can send a conflict detection message for.
`VotePeriod` is the number of epochs in the past that a consumer can send a conflict detection message for.
`Rewards` defines how the reward pool tokens will be distributed between all the participants.

```go
Expand All @@ -98,16 +100,17 @@ type Rewards struct {
VotersRewardPercent github_com_cosmos_cosmos_sdk_types.Dec // the jury portion
}
```

## Queries

The Conflict module supports the following queries:

| Query | Arguments | What it does |
| ---------- | --------------- | ----------------------------------------------|
| `params` | none | show the params of the module |
| `consumer-conflicts` | consumer (string) | shows all the reported and active conflicts by a consumer |
| `list-conflict-vote` | none | shows all active conflicts |
| `show-conflict-vote` | voteID (string) | shows a specific active conflict |
| Query | Arguments | What it does |
| -------------------- | ----------------- | --------------------------------------------------------- |
| `params` | none | show the params of the module |
| `consumer-conflicts` | consumer (string) | shows all the reported and active conflicts by a consumer |
| `list-conflict-vote` | none | shows all active conflicts |
| `show-conflict-vote` | voteID (string) | shows a specific active conflict |

## Transactions

Expand All @@ -118,12 +121,14 @@ for more information look [here](../../proto/lavanet/lava/conflict/tx.proto).

The conflict module has the following events:

| Event | When it happens |
| ---------- | --------------- |
| `response_conflict_detection` | A new conflict has been opened, which involves all of the jury providers. It is now entering the commit stage |
| `conflict_vote_reveal_started` | conflict has transitioned to reveal state |
| `conflict_vote_got_commit` | provider commited his vote |
| `conflict_vote_got_reveal` | provider revealed his vote |
| `conflict_unstake_fraud_voter` | provider was unstaked due to conflict |
| `conflict_detection_vote_resolved` | conflict was succesfully resolved |
| `conflict_detection_vote_unresolved` | conflict was not resolved (did not reach majority) |
| Event | When it happens |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
| `response_conflict_detection` | A new conflict has been opened, which involves all of the jury providers. It is now entering the commit stage |
| `conflict_vote_reveal_started` | conflict has transitioned to reveal state |
| `conflict_vote_got_commit` | provider commited his vote |
| `conflict_vote_got_reveal` | provider revealed his vote |
| `conflict_unstake_fraud_voter` | provider was unstaked due to conflict |
| `conflict_detection_vote_resolved` | conflict was succesfully resolved |
| `conflict_detection_vote_unresolved` | conflict was not resolved (did not reach majority) |
| `conflict_detection_same_provider` | same provider finalization conflict was detected |
| `conflict_detection_two_providers` | finalization conflict between two providers was detected |

0 comments on commit 2bacbf6

Please sign in to comment.