> ## 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.

# Slashing manager

# SlashingManager

The `SlashingManager` contract (Solidity name `NotareumSlashingManager`) applies economic penalties to validators who misbehave. It is the single contract authorized to reduce a validator's stake in `ValidatorStaking` outside of normal cooldown withdrawal. Slashing is triggered by `VerificationEngine` on successful disputes, by the dispute judge on manual findings, or by automated monitors for downtime.

## Slash reasons

```solidity theme={"system"}
enum SlashReason {
    WrongAttestation,   // validator voted against the later-confirmed truth
    MissedAttestation,  // validator assigned but did not attest before deadline
    Downtime,           // validator offline beyond grace period
    Collusion,          // governance-finalized evidence of coordinated misbehavior
    DoubleSigning       // conflicting attestations on same request
}
```

Each reason carries its own rate schedule and destination split.

## Rate schedule by tier and reason

Rates are expressed as basis points of the validator's bonded stake. Maximum rates are governance-adjustable up to the per-tier ceiling.

| Reason             |        Basic | Professional |   Enterprise | Institutional |
| ------------------ | -----------: | -----------: | -----------: | ------------: |
| Wrong attestation  |     200 (2%) |     400 (4%) |     600 (6%) |      800 (8%) |
| Missed attestation |    50 (0.5%) |     100 (1%) |   150 (1.5%) |      200 (2%) |
| Downtime           |   25 (0.25%) |    50 (0.5%) |   75 (0.75%) |      100 (1%) |
| Collusion          | 10000 (100%) |        10000 |        10000 |         10000 |
| Double signing     |   5000 (50%) |   7500 (75%) | 10000 (100%) |  10000 (100%) |

The aggregate slash applied in any 24-hour window is bounded by the tier's `maxSlashRate` (Basic 10%, Professional 15%, Enterprise 20%, Institutional 25%) except for terminal categories (Collusion, Double signing at Enterprise+).

## Destination split

Slashed funds are routed deterministically by reason:

| Reason             | Burn | Treasury | Disputer |
| ------------------ | ---: | -------: | -------: |
| Wrong attestation  |  25% |      25% |      50% |
| Missed attestation |  50% |      50% |       0% |
| Downtime           |  50% |      50% |       0% |
| Collusion          |  50% |      25% |      25% |
| Double signing     |  50% |      25% |      25% |

"Disputer" is the address that opened the successful dispute (for adversarial reasons) or `0x0` for automated reasons (then the share folds into treasury).

## Functions

### `slash`

```solidity theme={"system"}
function slash(
    address validator,
    SlashReason reason,
    bytes32 evidenceHash,
    address disputer
) external returns (uint256 amountSlashed);
```

Callable only by `VerificationEngine` (for dispute outcomes) or by the `SLASHER` role (held by the dispute judge or an approved watchdog). Pulls the computed amount out of `ValidatorStaking` via `applySlash`, splits it per the destination table, and distributes.

Reverts if:

* Reason/tier ceiling would be exceeded.
* Validator has insufficient bonded stake for the base amount (partial slash applied instead: the contract slashes what is available).
* Caller is not authorized for the reason.

Emits `Slashed(validator, reason, amountSlashed, evidenceHash, disputer)`.

### `reportDowntime`

```solidity theme={"system"}
function reportDowntime(address validator, uint64 firstMissedEpoch) external;
```

Callable by any watcher. Checks that `validator` has missed attestations across `k` consecutive epochs (default `k = 4` weeks) and triggers a downtime slash if so. This provides a liveness incentive without requiring a manual dispute.

### Governance setters

```solidity theme={"system"}
function setRate(SlashReason reason, Tier tier, uint16 bps) external;  // PROTOCOL_ADMIN
function setSplit(SlashReason reason, uint16 burn, uint16 treasury, uint16 disputer) external; // PROTOCOL_ADMIN
function setTierCeiling(Tier tier, uint16 bps) external;               // PROTOCOL_ADMIN
function setWatchdog(address addr, bool allowed) external;             // PROTOCOL_ADMIN
```

All setters are delay-gated and require the `PROTOCOL_ADMIN` role, held by a 14-day timelock.

### Views

```solidity theme={"system"}
function getRate(SlashReason reason, Tier tier) external view returns (uint16 bps);
function getSplit(SlashReason reason) external view returns (uint16 burn, uint16 treasury, uint16 disputer);
function tierCeiling(Tier tier) external view returns (uint16 bps);
```

## Interaction with ValidatorStaking

`SlashingManager` is the only caller that `ValidatorStaking.applySlash` accepts (enforced via `AccessManager`). The call signature:

```solidity theme={"system"}
// In ValidatorStaking
function applySlash(address validator, uint256 amount) external returns (uint256 actual);
```

`applySlash` deducts up to `amount` from bonded stake first, then (if insufficient) from `pendingUnstake`. It returns the amount actually slashed. `SlashingManager` uses the returned value as the basis for destination splitting, so under-collateralized validators slash to less than the full intended amount.

## Flow on successful dispute

```mermaid theme={"system"}
sequenceDiagram
    participant Eng as VerificationEngine
    participant Gov as Dispute Judge
    participant SM as SlashingManager
    participant VS as ValidatorStaking
    participant T as Treasury
    participant B as Burn
    participant D as Disputer

    Gov->>Eng: resolveDispute(disputantWins=true)
    Eng->>SM: slash(offender, WrongAttestation, evidenceHash, disputer)
    SM->>VS: applySlash(offender, amount)
    VS-->>SM: actualSlashed
    SM->>T: 25%
    SM->>B: 25%
    SM->>D: 50%
    SM-->>Eng: OK
```

## Freeze

A validator who is slashed for Collusion or Double signing is frozen: `ValidatorStaking.isActive(validator)` returns false for the governance-set freeze window (default 30 days). During the freeze, the validator cannot submit attestations even if their remaining stake is above the Basic minimum. The freeze is applied via `ValidatorStaking.setFreeze`, which `SlashingManager` has permission to call.

## Events

```solidity theme={"system"}
event Slashed(
    address indexed validator,
    SlashReason indexed reason,
    uint256 amount,
    bytes32 evidenceHash,
    address disputer
);
event SlashSplit(
    uint256 toBurn,
    uint256 toTreasury,
    uint256 toDisputer
);
event ValidatorFrozen(address indexed validator, uint64 until);
event RateUpdated(SlashReason reason, Tier tier, uint16 bps);
event SplitUpdated(SlashReason reason, uint16 burn, uint16 treasury, uint16 disputer);
event WatchdogSet(address indexed addr, bool allowed);
```

## SDK usage

Consumers rarely call SlashingManager directly; the SDK provides read helpers and dispute-flow convenience wrappers.

```typescript theme={"system"}
import { Notareum, SlashReason, Tier } from "@notareum/sdk";

const ntm = Notareum({ provider, signer, contracts });

// Read rate tables
const wrongProf = await ntm.staking.slashing.getRate(
  SlashReason.WrongAttestation,
  Tier.Professional
); // 400 bps

// Check if a validator is frozen
const active = await ntm.staking.isActive(valAddr);

// Report downtime
await ntm.staking.slashing.reportDowntime(valAddr, firstMissedEpoch);
```

## Invariants

1. The sum of destination splits for each reason equals 10000 bps.
2. The total slashed amount in any 24-hour window for a validator does not exceed `tierCeiling(tier)` unless the reason is terminal (Collusion, Enterprise+ Double signing).
3. `SlashingManager` is the sole caller accepted by `ValidatorStaking.applySlash`.
4. Every slash event is accompanied by an `evidenceHash` whose preimage is publicly accessible for adversarial transparency.

## Related pages

* [ValidatorStaking](validator-staking.md)
* [VerificationEngine](verification-engine.md)
* [FeeManager](fee-manager.md)
* [AccessManager](access-manager.md)
* [Slashing protocol doc](../protocol/slashing.md)