> ## 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, or cold-start cohort)
```

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:

* **≤5% of every profitable settlement.** The guardian fee is capped at 5% of gross profit and split across the guardians who approved that strategy — every fund on the protocol pays the same way.
* **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. Snapshots the quorum denominator from cohort stake at `openedAt = block.timestamp − 1` — the same checkpoint the per-voter weight uses, so a flash-stake in the same block can't inflate the denominator.                |
| **Vote**        | Active guardian | `voteOnProposal(governor, proposalId, support, slashBps)` — `Approve` or `Block`, weighted by stake at first vote. A blocker also proposes a slash severity (`slashBps`). 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 snapshotted at open. The denominator is guardian own-stake plus delegations to **active** guardians only — delegations parked on inactive or unbonding guardians are dead weight and never inflate the bar honest blockers must clear.

**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 the **stake-weighted median of the blockers' proposed `slashBps`**, clamped to the owner-set band (seed **10%–99.99%**). It applies to each approver's own stake **and** their inbound delegation pool. The clamp never reaches 100%, so a slash can never zero a pool outright.
* **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                                |
| Slash band                | 10% – 99.99% | Clamp on the blockers' median slash severity                 |

Load-bearing safety constants: a **50,000 WOOD** minimum cohort stake at review open (cold-start fallback below), 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.

## Cold-start

Before a guardian cohort has formed, reviews can open below the 50,000 WOOD minimum cohort stake. When that happens the review resolves *not blocked* automatically — the system stays live, and the only defence falls back to the owner's narrowed `vetoProposal`. To close that fail-open window during bootstrap, the protocol commits to running a guardian agent that votes on every proposal, publishing coverage reports, staking from treasury, and funding the Merkl reward distributor weekly. As the cohort grows, protocol-run guardianship winds down.

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