[Contract]: Timelock and multi-signer governance for sensitive admin operations

[grantfox-oss]

Every privileged action in CleverVault (pause, add_asset, remove_asset, set_stale_threshold, set_max_active_tasks, update_admin, and any future upgrade/set_fee) is gated by a single admin key with immediate effect. A compromised or rushed admin key can whitelist a malicious asset, change parameters, or (with upgradeability) swap the WASM instantly, with no delay for users to react. For a contract custodying user funds, sensitive operations should pass through a timelock (and ideally require multiple signers), which is standard practice and a substantial governance feature.

Goal

Introduce a governance layer that routes a defined set of sensitive operations through a queue-then-execute timelock, with an optional M-of-N approval, while leaving routine operations responsive.

Proposed surface (signatures only)

• queue_action(env, signer, action: GovAction, eta: u64) -> u64 returning an action id
• execute_action(env, signer, action_id) — only after eta, only if approvals met
• cancel_action(env, signer, action_id)
• Optional multi-sig: set_signers(env, admin, signers: Vec<Address>, threshold: u32), and per-action approve_action(env, signer, action_id)
• GovAction enum covering the sensitive set (pause config, asset whitelist changes, threshold/cap changes, admin rotation, upgrade, fee changes)
• ActionQueuedEvent, ActionExecutedEvent, ActionCancelledEvent

Requirements and constraints

• A configurable minimum delay (e.g. >= 1 hour, admin-set with a floor) between queue and execute.
• Decide and document which operations are "sensitive" (timelocked) vs "safe/immediate" (e.g. pause may need to stay immediate for incident response; if so, keep pause immediate but timelock unpause, and justify).
• If multi-sig is included, execute_action must verify threshold distinct approvals.
• Backwards compatibility: provide a migration/opt-in so the current single-admin deployment keeps working until governance is configured.
• All existing per-operation auth checks remain as the inner authorization.

Edge cases

• Execute before eta (reject).
• Execute an already-executed or cancelled action (reject).
• Threshold not met (reject).
• Re-queue of an identical action (allowed, distinct ids).
• Admin rotation routed through governance must not lock the contract out (test the full rotation path).

Acceptance criteria

• Sensitive operations can only take effect via queue-then-execute after the timelock
• Optional M-of-N approvals enforced when signers are configured
• Immediate-vs-timelocked operation split is documented and justified
• Events emitted for queue/execute/cancel
• Tests cover: early-execute rejection, threshold enforcement, cancel, full admin-rotation via governance, and pause/incident path
• cargo test and cargo clippy --all-targets -- -D warnings pass

Pointers

• contracts/agent-vault/src/lib.rs: all admin-gated functions, VaultError, DataKey.
• Pairs with issue feat(agent-vault): emit events when assets are added/removed from the whitelist (#37) #54 (upgradeability) — upgrade should be a governed action.

Notes for contributors

Comment with the sensitive/immediate operation split and your timelock storage design before implementing. See CONTRIBUTING.md.

[emmyokolo2525-cyber]

Am a full-Stack Engineer focused on frontend, backend, APIs, automation, and modern web technologies. Passionate about solving real-world problems, contributing to open source, and delivering clean, scalable, review-ready solutions.

[Lansa-18]

Hi, I'd like to work on this.

I'll add the GovAction enum covering the sensitive operation set, queue_action, execute_action, cancel_action, approve_action, and set_signers with a configurable minimum delay (admin-set with a floor), M-of-N approval enforcement when signers are configured, and backwards compatibility so the current single-admin deployment keeps working until governance is configured. pause stays immediate for incident response while everything else (unpause, add_asset, remove_asset, set_stale_threshold, set_max_active_tasks, update_admin, upgrade, set_fee) goes through the timelock. Events fire on queue, execute, and cancel, all existing per-operation auth checks remain as inner authorization, and tests will cover early-execute rejection, threshold enforcement, cancel, re-queue producing distinct IDs, full admin rotation via governance, and the pause/incident path.

[BountySpaghetti]

Hello, I’m interested in working on this issue and would appreciate being assigned to it. Thank you.

[grantfox-oss]

🦊 GrantFox — @BountySpaghetti has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #103)
2. Your PR will be reviewed by the clevercon-protocol maintainers

Good luck! Track your progress on GrantFox.