Guardian Review

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.

​

Lifecycle change

Before PR #229:
  Draft → Pending → Approved → Executed → Settled
                        │           │
                        └ Rejected  └ (emergencySettle with arbitrary calldata — unbounded owner power)

V1 (PR #229):
  Draft → Pending → GuardianReview → Approved → Executed → Settled
                          │                          │
                          ├ Rejected (block quorum)  ├ Settled (settleProposal / unstick)
                          │   └ early Approvers slashed
                          │                          └ EmergencySettleReview → Settled
                          └ Rejected (owner veto — Pending state only)    │
                                                                          └ Rejected (block quorum)
                                                                              └ owner bond slashed

• Guardians cannot act before voteEnd — they review the already-approved calldata, not drafts.
• Owner’s unilateral vetoProposal is narrowed to Pending. Once in GuardianReview, only the guardian block quorum can reject.
• Owner’s emergencyCancel is narrowed to Draft and Pending.
• Post-execution, unstick(proposalId) is owner-instant for stuck vaults (pre-committed calls only). Any custom calldata goes through EmergencySettleReview.

​

GuardianRegistry — contract surface

​

Guardian role

​

Vault owner role

​

Emergency-settle review

​

Epoch-based Block-side rewards

​

Slashing

• Cleaner regulatory posture — slash is not protocol-controlled revenue.
• Aligns with WOOD scarcity narrative.
• Removes any treasury-capture incentive to over-slash.

• Approvers slashed inside resolveReview when blocked == true. Stake zeroed, _totalGuardianStake decremented, single bulk wood.transfer at the end (CEI). If the transfer reverts, the amount is recorded to _pendingBurn[address(this)] and anyone can later call flushBurn() to retry. State transition already committed.
• Owner slashed inside resolveEmergencyReview when blocked == true. Same CEI + pull-burn pattern.
• Cap: _slashApprovers is bounded by MAX_APPROVERS_PER_PROPOSAL = 100 to keep gas deterministic. Blockers are uncapped (no token transfer per blocker, only epoch-weight updates) — capping would be a DoS vector against honest defence.

​

Appeal path

1. Slashed party opens a forum case within 30 days with simulation / calldata analysis / reasoning.
2. veWOOD voters vote on the appeal (quorum / threshold set by tokenomics governance).
3. If upheld, the protocol multisig calls refundSlash(recipient, amount) — permissioned, drawing from the dedicated slashAppealReserve.
4. Hard-coded per-epoch cap: MAX_REFUND_PER_EPOCH_BPS = 2000 (20%). A compromised multisig cannot drain the reserve in a single call.
5. fundSlashAppealReserve(amount) tops up the reserve; owner-only, not timelocked since additions are always safe.

​

Pause + 7-day deadman

​

Parameters (initial values)

​

Cold-start: guardian-of-last-resort

• Running a guardian agent that votes on every proposal across every registered vault.
• Publishing weekly guardian-coverage reports in the Sherwood forum.
• Staking ≥ minGuardianStake from protocol treasury.
• Funding epochBudget weekly during the bootstrap window — fundEpoch(currentEpoch, X) at the start of each epoch, sized above expected guardian gas costs.

​

Known attack surfaces (V1-accepted)

• Blocker free-ride / DoS. Block voters have no stake at risk (slashing only hits Approvers). A 30%-stake cartel can Block every proposal across every vault at zero cost. Mitigations — correct-Approve rewards, shareholder challenge, reputation-weighted quorum — are deferred to V1.5 / V2.
• Keeper incentive for resolveReview. The function is permissionless but gas-expensive (~500k gas at the 100-approver cap). V1 acceptance: the next executeProposal call forces resolution and the proposer pays — proposer becomes an unwilling keeper. V2 can add a small gas rebate from the burn amount.
• Approver cap saturation on popular proposals. A guardian who voted Block early and wants to switch to Approve on a proposal with 100 existing Approvers reverts with NewSideFull. Block side is uncapped, so switching the other direction is always available.

​

Integrator guidance

• Don’t poll getProposalState(id) to detect Rejected. After voteEnd the view returns GuardianReview until on-chain resolution runs. Subscribe to the GuardianReviewResolved(proposalId, blocked) event, or call registry.resolveReview(id) yourself (permissionless) to force resolution.
• Execute path still state == Approved. No integrator-visible change to executeProposal — the new gate is earlier.
• Timing: reviewEnd = voteEnd + reviewPeriod, executeBy = reviewEnd + executionWindow. All stamped at proposal creation — no mid-flight drift.