> ## Documentation Index
> Fetch the complete documentation index at: https://docs.notareum.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Dispute resolution

# Dispute Resolution

Any party with evidence of validator misconduct can report a dispute. Disputes are resolved by an arbitration committee that reviews submitted evidence and renders one of three verdicts: guilty, innocent, or dismissed. Guilty verdicts slash the validator and reward the reporter. Innocent verdicts burn the reporter's bond. Dismissal returns the bond without penalty. This page documents bond amounts, the lifecycle, and the outcomes.

## The three outcomes

```mermaid theme={"system"}
flowchart TD
    A[reportValidator] --> B[Post NOTA bond]
    B --> C[evidenceHash stored<br/>raw evidence off-chain]
    C --> D[Arbitration committee]
    D --> E{Verdict}
    E -->|Guilty| F[Validator slashed]
    F --> G[Reporter gets bond back<br/>+ 10% of slash]
    F --> H[Slashed tokens burned]
    E -->|Innocent| I[Bond burned]
    I --> J[Validator stake unaffected]
    E -->|Dismissed| K[Bond returned to reporter]
    K --> L[No slashing]
```

## Reporting a dispute

```solidity theme={"system"}
function reportValidator(
    address validator,
    bytes32 resourceId,
    bytes calldata evidence
) external returns (uint256 disputeId);
```

Rules:

* `validator` MUST be an active validator (`stakedAmount >= 10,000 NOTA`).
* `evidence` MUST NOT be empty. It is hashed on-chain (`keccak256(evidence)`); raw bytes are not stored.
* The reporter posts a tier-dependent bond in NOTA.

Bond amounts are determined by the accused validator's current tier:

| Dispute Level | Bond        |
| ------------- | ----------- |
| BASIC         | 1,000 NOTA  |
| ENHANCED      | 5,000 NOTA  |
| INSTITUTIONAL | 25,000 NOTA |

Mapping from tier to dispute level:

* `INSTITUTIONAL` or `ENTERPRISE` tier validator: dispute level is `INSTITUTIONAL` (25K NOTA bond).
* `PROFESSIONAL` tier validator: dispute level is `ENHANCED` (5K NOTA bond).
* `BASIC` tier validator: dispute level is `BASIC` (1K NOTA bond).

## Evidence handling

Evidence is hashed on-chain but stored off-chain. The on-chain `evidenceHash` provides tamper-evidence; the raw bytes are not part of the contract state. Implementations SHOULD use decentralized storage like IPFS for evidence and submit the CID as the evidence payload, enabling any party to retrieve and verify the evidence independently.

## Dispute resolution

```solidity theme={"system"}
function resolveDispute(uint256 disputeId, bool guilty) external restricted;
```

Restricted to `ROLE_SLASHING_ARBITRATOR`. The arbitration committee reviews evidence off-chain and renders a verdict.

### Guilty verdict

1. The validator's current tier determines slash rate.
2. `slashedAmount = (stakedAmount * slashBps) / 10000`.
3. Tokens are transferred from `NotareumValidatorStaking` to `NotareumSlashingManager`.
4. Slashed tokens are forwarded to `burnAddress`.
5. `reporterReward = (slashedAmount * 1000) / 10000` (10%).
6. Reporter receives `bondAmount + reporterReward`.

### Innocent verdict

1. Reporter's bond is transferred to `burnAddress` as anti-spam.
2. Validator's stake is unaffected.

### Dismissal

```solidity theme={"system"}
function dismissDispute(uint256 disputeId) external restricted;
```

Authorized dismissal returns the bond without penalty. Used when a dispute is filed in error (wrong validator, wrong resource, insufficient evidence).

## Dispute struct

```solidity theme={"system"}
struct Dispute {
    address reporter;
    address validator;
    bytes32 resourceId;
    bytes32 evidenceHash;
    uint256 bondAmount;
    DisputeLevel level;
    DisputeStatus status;
    uint256 createdAt;
    uint256 resolvedAt;
}
```

## Dispute lifecycle

```
OPEN --> RESOLVED_GUILTY
OPEN --> RESOLVED_INNOCENT
OPEN --> DISMISSED
```

Disputes only transition from `OPEN`. Once resolved or dismissed, they are final.

## Example: reporter math

A BASIC tier validator with 10,000 NOTA staked gets caught falsely attesting. The reporter posts 1,000 NOTA bond. The arbitration committee rules guilty.

* Slash: 25% of 10,000 = 2,500 NOTA burned
* Reporter reward: 10% of 2,500 = 250 NOTA
* Reporter receives: 1,000 (bond) + 250 (reward) = 1,250 NOTA
* Validator loses: 2,500 NOTA from stake

An ENTERPRISE validator with 250,000 NOTA gets caught in a coordinated collusion.

* Slash: 50% of 250,000 = 125,000 NOTA burned
* Reporter posted: 25,000 NOTA bond
* Reporter reward: 10% of 125,000 = 12,500 NOTA
* Reporter receives: 25,000 + 12,500 = 37,500 NOTA

## Why innocent verdicts burn bonds

Anti-spam. If bonds were returned on innocent verdicts, frivolous dispute spam would be free and the arbitration committee would drown in noise. Burning the bond imposes a real cost on bad-faith reports while preserving ample reward for good-faith whistleblowers.

## Arbitration committee

In v1.0, arbitration is centralized to `ROLE_SLASHING_ARBITRATOR`. This role SHOULD be held by a multisig with a minimum 3-of-5 threshold. The committee is a bootstrapping compromise on the path to fully decentralized on-chain arbitration via governance voting in later protocol versions.

## Example code

**Reporter (TypeScript):**

```typescript theme={"system"}
const bond = 1_000n * 10n ** 18n;
await ntm.fee.approveNotaForDispute(bond);

const evidenceBytes = new TextEncoder().encode(
  "ipfs://QmEvidenceCID/dispute-evidence.json"
);
const tx = await ntm.slashing?.reportValidator(
  validatorAddress,
  resourceId,
  evidenceBytes,
);
```

**Arbitrator:**

```typescript theme={"system"}
await ntm.slashing?.resolveDispute(disputeId, true);  // guilty
```

## Related pages

* [Slashing](slashing.md) for slash mechanics
* [Staking and Tiers](staking-and-tiers.md) for tier thresholds
* [Governance](governance.md) for progressive decentralization of arbitration
* [SlashingManager contract](../smart-contracts/slashing-manager.md)