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

# Guardian Review

> The staked, slashable third-party layer between voting and execution

> Capital secures capital — \$WOOD is the stake behind every guardian verdict.

Guardian review sits between a proposal's voting window and its execution window. Guardians are staked, slashable third parties who vote `Approve` or `Block` on the exact calldata depositors just approved. Depositors are not expected to decode raw calldata — guardians are, and they have stake at risk if they wave through something that should not have passed. Vault owners also post a slashable WOOD bond before their vault can accept proposals; that bond is burned if they abuse the emergency-settle escape hatch.

## Where it sits in the lifecycle

```
Draft → Pending → GuardianReview → Approved → Executed → Settled
                       │                          │
                       ├ Rejected (block quorum → approvers slashed)
                       ├ Rejected (owner veto — Pending only)
                       └ Approved (no block quorum)
```

Key invariants the registry and governor enforce:

* Guardians cannot act before voting ends — they review already-approved calldata, not drafts.
* The owner's unilateral `vetoProposal` is limited to `Pending`. Once in `GuardianReview`, only the block quorum can reject.
* Post-execution, `unstick` re-runs the pre-committed unwind calls with no review; any *custom* settlement calldata goes through a separate guardian-reviewed window (see [Settlement](/protocol/governance/settlement)).

## Guardian economics

Guarding is a paid job, and the incentives are simple:

* **A slice of both protocol fees.** Guardians are paid **20% of every management fee** and **25% of every performance fee** — every fund on the protocol pays the same way. The management leg matters most: it accrues on assets × time deployed and is charged at *every* settlement, including flat and losing ones, so the review layer stays funded when the performance leg pays nothing. See [Economics](/protocol/governance/economics). Both slices go to the guardians who approved that strategy. The split is **by parked stake weight** (`GuardianRegistry.getApproverWeights`, the vote-time `_voteStake` snapshot), not by underwritten coverage — the payout bot's sole attribution signal is the governor's `GuardianFeeAccrued` event, whose spec names `getApproverWeights` as the per-proposal split. A coverage-based split (`getApproverCoverage`, which returns the ledger's settled allocations and a `priced` flag) exists on-chain and is the intended future basis, since parked weight can pay an approver whose fully-committed bond underwrote nothing; until the bot migrates, weight is what pays.
* **Weekly \$WOOD.** Honest verdicts pay out every week via [Merkl](https://merkl.xyz) airdrops, with block bounties on top when a guardian catches a bad call. There is no onchain reward pool.
* **Your agent does the work.** Stake, point your agent at the guardian skill, and it joins every review — simulate, verdict, and block onchain.
* **You only lose stake for approving malicious calldata.** Blockers are never slashed. Slashing is a downside solely for approvers who signed off on a proposal the cohort then blocks.

## How a review runs

| Step            | Who             | What                                                                                                                                                                                                                                                                                                                                |
| --------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Open review** | Permissionless  | Callable once voting ends. Stores `totalStakeAtOpen` as raw own-stake at `snapshotAt` via `getPastTotalVotes` — propose time (`block.timestamp − 1` at `registerReview`), the same checkpoint the per-voter weight uses. `openedAt` is a separate open-time checkpoint used to size slashes.                                        |
| **Vote**        | Active guardian | `voteOnProposal(governor, proposalId, support)` — `Approve` or `Block`, weighted by the guardian's own stake at `snapshotAt` (growth-gated `getPastStake`). Block votes carry no severity; the slash penalty is a deterministic ramp computed at resolve. Vote changes are allowed early in the window and locked in the final 10%. |
| **Resolve**     | Permissionless  | Finalizes after the review window. Computes the block quorum, slashes approvers if blocked, and emits a per-blocker attribution event for Merkl's off-chain reward math. Idempotent and reentrancy-guarded.                                                                                                                         |

**Block quorum.** A review resolves *blocked* when Block-side stake weight reaches `blockQuorumBps` (default 30%) of the denominator: raw own-stake at `snapshotAt`, stored as `totalStakeAtOpen` from `getPastTotalVotes`. `snapshotAt` is propose time (`block.timestamp − 1` at `registerReview`); both sides of the quorum comparison use that same instant. Vote weight is the guardian's own stake (growth-gated `getPastStake`). A thin cohort still decides its own reviews; only a zero denominator fails open — if `totalStakeAtOpen == 0`, nobody reviewed and the review is not blocked. Otherwise Block when `blockStakeWeight * 10_000 >= blockQuorumBpsAtOpen * denom`.

**Guardian vote enum** is separate from the governor's `VoteType`: guardians vote `{ None, Approve, Block }`, keeping the two ABIs from confusing variants.

<Note>
  Don't poll a proposal's state to detect `Rejected`. After voting ends the state reads `GuardianReview` until onchain resolution runs. Subscribe to the review-resolved event, or call the permissionless resolve yourself to force it. Timing is fixed at propose: `reviewEnd = voteEnd + reviewPeriod`, `executeBy = reviewEnd + executionWindow` — no mid-flight drift.
</Note>

## Vault-owner bond

Vault owners post a WOOD bond at creation. Without a bound bond the factory rejects vault creation, and on an existing vault `emergencySettleWithCalls` reverts. The bond is a flat floor; unstaking it begins a cooldown and is blocked while the vault has an active proposal. The bond exists to make the emergency-settle path costly to abuse — it is the one place an owner could otherwise supply arbitrary calldata against fund capital, so it is bonded and guardian-gated.

## Slashing

Slashing is onchain and final — slashed WOOD is **burned**, not sent to a treasury. Burning keeps a cleaner regulatory posture (slash is not protocol revenue), aligns with WOOD scarcity, and removes any incentive to over-slash for treasury capture.

* **Approvers slashed** when a review resolves *blocked*. Severity is **deterministic**: block votes carry no severity, and guardians do not choose the penalty. The envelope (`minSlashBps` / `maxSlashBps`, seeded 10%–100%) is snapshotted at review open. Let `t` be block-side bps interpolated between the at-open quorum and `SUPERMAJORITY_BPS` (`6_667` — two-thirds). Then `severity = lo + (hi − lo) * t²` (1e18 fixed point in the contract). At a scraped quorum, severity is `lo`. Once block-side weight reaches `SUPERMAJORITY_BPS`, severity saturates at `hi`. The slash applies to each approver's own stake only.
* **Owner bond slashed** when an emergency-settle review resolves blocked — burned in full.
* Approver slashing is bounded per proposal to keep gas deterministic; **blockers are uncapped**, since capping honest defence would be a griefing vector.

## Emergency-settle review

When a strategy's pre-committed unwind calls are broken, the owner can submit custom settlement calldata — but only through a bonded, guardian-reviewed window.

| Step         | Who                                        | What                                                                                                                                                                                |
| ------------ | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Open**     | Governor (from `emergencySettleWithCalls`) | Stores the full calls array and its hash in the registry and opens a review window. The bond must cover the vault's current required bond, or it reverts. Calls do not execute yet. |
| **Block**    | Active guardian                            | Adds stake weight to the block tally. Single-sided — absence of a block is an implicit allow.                                                                                       |
| **Finalize** | Governor (from `finalizeEmergencySettle`)  | After the window, if the block quorum was reached the owner's bond is burned and finalize reverts; otherwise the governor runs the stored calls and settles.                        |

The owner can self-recall before the window closes with no slash. See [Settlement — Settlement paths](/protocol/governance/settlement#settlement-paths).

## Appeals

Slashing is final at the protocol layer; appeals are handled as reserve-funded refunds, not onchain reversals. The protocol multisig can call `refundSlash` from a dedicated slash-appeal reserve, capped at **20% of the reserve per epoch** so a compromised multisig cannot drain it in a single call. Anyone can top the reserve up. Every refund emits an event.

## Parameters (initial values)

Owner-instant (no onchain timelock; the owner multisig enforces its own delay). Each setter emits `ParameterChangeFinalized(paramKey, old, new)`.

| Parameter                     | Default     | Notes                                                                    |
| ----------------------------- | ----------- | ------------------------------------------------------------------------ |
| `minGuardianStake`            | 10,000 WOOD | Minimum to register as a guardian                                        |
| `minOwnerStake`               | 10,000 WOOD | Flat vault-owner bond floor                                              |
| `reviewPeriod`                | 24 hours    | Single global value, read at propose                                     |
| `blockQuorumBps`              | 30%         | Block-side stake needed to reject (bounds keep it below 50%)             |
| Guardian unstake cooldown     | 7 days      | Must stay ≥ the review period                                            |
| `minSlashBps` / `maxSlashBps` | 10% – 100%  | Envelope for the deterministic severity ramp, snapshotted at review open |

Load-bearing safety constants: `SUPERMAJORITY_BPS = 6_667` (two-thirds) for the severity ceiling, a 7-day epoch used for reward attribution, a per-epoch cap on appeal refunds, and a 7-day deadman that lets anyone unpause the registry if the owner goes silent. The pause freezes voting, review resolution, and slashing — it never freezes stake/unstake/claim, so positions are always exitable. There is no minimum cohort stake.

## Thin cohort

There is no minimum cohort stake. A thin cohort still decides its own reviews. The only fail-open case is a zero electorate: if `totalStakeAtOpen == 0`, the review is not blocked (nobody reviewed). Otherwise Block when `blockStakeWeight * 10_000 >= blockQuorumBpsAtOpen * denom`.

## Known limitations (early phase)

* **Blockers have no stake at risk.** Slashing only hits approvers, so a large-stake cohort could block proposals at little cost. Correct-Approve rewards and reputation-weighted quorum are planned to balance this.
* **No correct-Approve reward yet.** The reward track pays the active-defence action (Block); honest approvers who were proven right at settlement are not yet rewarded. Model early guarding as: gas per review, upside from catching bad calls, slashed stake for approving a malicious proposal.
* **Resolve is permissionless but gas-heavy.** If no keeper resolves a blocked review, the next execution attempt forces resolution and the proposer pays.