[huangji6693-max]

Closes #311

Summary

Adds multi-signature guardian veto & proposal storage purge (veto_and_purge), a 30-day rolling epoch circuit breaker rate limiter (MAX_UPGRADES_PER_EPOCH = 1 per CIRCUIT_BREAKER_EPOCH_SECONDS), and an emergency pause (emergency_pause) with time-decayed post-pause recovery (UNWIND_RECOVERY_WINDOW_SECONDS) to contracts/timelock.

Key Changes

1. Guardian Multi-Sig Veto & Storage Purge (contracts/timelock/src/lib.rs):
   • configure_guardians(guardians, threshold) registers a multi-sig guardian council with strict duplicate/quorum validation (GovernanceError::InvalidGuardianSet).
   • veto_and_purge(signers, id) verifies guardian multi-sig quorum (GovernanceError::InsufficientGuardianQuorum) without administrative keys, cancels malicious queued proposals prior to ETA execution, removes the proposal payload from persistent storage, and writes an immutable tombstone (SecurityKey::PurgedProposal(id) / is_purged).
2. Circuit Breaker Rate Limiter (contracts/timelock/src/lib.rs):
   • Enforces a global cap of MAX_UPGRADES_PER_EPOCH = 1 contract upgrade / state migration per CIRCUIT_BREAKER_EPOCH_SECONDS (30-day window), rejecting additional upgrades in the same epoch with GovernanceError::CircuitBreakerTripped and automatically resetting when the next 30-day epoch begins.
3. Emergency Pause & Graceful Post-Pause Time-Decayed Unwinding (contracts/timelock/src/lib.rs):
   • emergency_pause(signers) allows the guardian multi-sig to immediately halt contract dispatch without admin keys for MAX_PAUSE_DURATION_SECONDS (14 days).
   • After 14 days, if not cooperatively cleared earlier via unpause(), the contract automatically enters a 7-day (UNWIND_RECOVERY_WINDOW_SECONDS) time-decayed recovery phase where get_recovery_surcharge() decays linearly from 7 days to 0, preventing perpetual governance deadlocks while extending pre-queued proposal expiries across the freeze.
4. Tests & Documentation (contracts/timelock/src/test.rs, docs/upgradeability.md):
   • 43/43 Soroban tests passing (cargo test -p timelock --features wasm-tests), cargo clippy --all-targets -- -D warnings clean, cargo fmt --check clean, and node scripts/ci/check-numeric-ids.mjs verified.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: e92023a2-9901-46d1-b79d-f8b0ea7a4527

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}