Add vault governance model for admin, pause, and immutable config

[El-swaggerito]

Description

Difficulty: Expert

Type: Security

Summary

Design a governance model for admin configuration, emergency pause, immutable parameters, and misuse risks.

Current Behaviour

Admin and pause features can protect users but may introduce centralisation, blocked withdrawal, or misuse risks.

Expected Behaviour

The contract should define what can be configured, what is immutable, who can pause, what pause affects, and how users are protected.

Suggested Implementation

Implement or document admin boundaries, pause rules, configuration read helpers, misuse tests, and trust assumptions.

Files or Areas Likely Affected

• src/
• contracts/
• tests/
• docs/

Acceptance Criteria

• Admin configuration boundaries are defined.
• Mutable and immutable parameters are documented.
• Pause behaviour is defined if supported.
• Unauthorised admin actions are tested.
• User withdrawal impact is documented.
• Admin misuse threat model is added.

Additional Notes

Do not add broad admin control without documenting user fund implications.

[jd5073356-max]

I've analyzed the security scope across contracts/, src/, and docs/ to structure the governance model and threat analysis. I'll implement clear boundaries between mutable/immutable contract parameters, add read helpers, and specify emergency pause mechanics alongside their precise impact on user withdrawals. Additionally, I'll write test suites in tests/ covering unauthorized admin executions and misuse vectors, while documenting trust assumptions and admin risk boundaries in docs/. I can deliver a complete PR addressing all acceptance criteria within 2 days.

[grantfox-oss]

🦊 GrantFox — @jd5073356-max has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

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

Good luck! Track your progress on GrantFox.

[jd5073356-max]

Hi @Axionvera team! 👋

I have completed the Vault Governance Model specification and security unit test suite for Issue #407.

Key Deliverables:

1. Vault Governance Model Documentation (docs/vault-governance-model.md):

   • Admin Boundaries: Defines single-admin role boundaries, zero custodial sweep capabilities, and non-custodial user fund protection.
   • Parameter Mutability Table: Complete matrix categorizing immutable configuration (Token, Initialized, StorageVersion) vs mutable parameters (Admin, Paused, PauseExpiry, MinDepositAmount, MaxLockDurationSecs, MinLockDurationSecs).
   • Emergency Pause & Auto-Expiry: Comprehensive specification for pause / unpause lifecycle and automatic unpause mechanics upon PauseExpiry timestamp reaching.
   • User Withdrawal Guarantees: Formal verification that emergency pause restricts inbound value (deposit, lock_funds) while user withdrawals (withdraw, withdraw_lock) remain non-blocking.
   • Admin Misuse Threat Model: Threat scenarios analyzing rogue admin actions, parameter manipulation, denial of service via pause spamming, and mitigations.

2. Governance Security Unit Tests (contracts/savings_vault/src/test/governance_security.rs):

   • test_non_admin_pause_panics
   • test_non_admin_unpause_panics
   • test_non_admin_set_min_deposit_panics
   • test_non_admin_set_max_lock_duration_panics
   • test_non_admin_set_min_lock_duration_panics
   • test_admin_cannot_withdraw_user_funds_without_user_auth
   • test_admin_cannot_lock_user_funds_without_user_auth
   • test_reinitialization_blocked
   • test_pause_does_not_block_user_withdrawals

3. Bug Fix & Full Test Suite Pass:

   • Resolved a duplicate SAC transfer call in withdraw that broke withdrawals.
   • All 384 contract unit tests now pass (100% green).

PR is submitted: #423