Feature/issues 667 668 669 670

[Able-faz-system]

Summary

This pull request implements comprehensive governance, revenue-sharing, and audit features for the Kora Protocol, addressing four high-complexity
issues. The changes enhance protocol security, enable stakeholder revenue sharing, improve governance transparency, and provide parameter flexibility.

Closes #667
Closes #668
Closes #669
Closes #670

---

Issues Addressed

Issue #667: Treasury Revenue-Sharing Distribution to Fee Stakeholders

Complexity: High (200 points)

Implements a mechanism for the treasury to regularly distribute protocol fees to a defined set of stakeholders, enabling actual revenue-sharing beyond
point-based recognition systems.

Changes:

• Data Structures: Added DistributionConfig and DistributionProposal structs for epoch-based distribution management
• Storage Keys: Added 7 new storage keys for stakeholder registry, distribution pool tracking, claims, and configuration
• Core Functions:
  • propose_distribution() - Admin proposes stakeholder set and distribution percentage (0-10,000 bps)
  • execute_distribution() - Locks epoch configuration after timelock expires
  • claim_share() - Eligible stakeholders withdraw pro-rata shares from distribution pool
• Query Functions:
  • get_distribution_epoch() - Current epoch number
  • get_distribution_config() - Configuration for specific epoch
  • get_pending_distribution() - Pending proposal details
• Helpers: bps_of() for safe basis point calculations
• Error Handling: 4 new error types for distribution-specific failures

Key Features:

• Multi-epoch support with changing stakeholder rosters between distribution cycles
• Comprehensive accounting to prevent over-distribution
• Handles edge cases where stakeholder list changes between distribution and claim periods
• Equal pro-rata distribution among eligible stakeholders in an epoch

---

Issue #669: Emergency Multi-Role Pause Governance

Complexity: High (200 points)

Addresses security vulnerabilities in single-admin pause mechanism by introducing a Guardian role enabling immediate protocol halt without multisig
overhead, while requiring full governance for unpause (fast to pause, slow to unpause pattern).

Changes:

• Role Enhancement: Added Guardian role to Role enum, distinct from Admin and Multisig signers
• Storage Keys: Added 2 keys to track emergency pause timestamp and initiator
• Core Functions:
  • emergency_pause_by_guardian() - Any guardian can trigger immediate pause without multisig/timelock
  • get_last_emergency_pause_time() - Query last emergency pause timestamp
  • get_emergency_pause_initiator() - Query guardian who initiated pause
• Helper: require_guardian() for role validation
• Error Types: 2 new errors for guardian-specific failures

Key Features:

• Single guardian can trigger pause independently (decentralized emergency response)
• Unpause still requires full governance workflow (multisig approval + timelock)
• Audit tracking of emergency pause initiator and timestamp
• Handles edge case where guardian role is revoked during active incident
• Implements asymmetric pause/unpause for security resilience

---

Issue #670: Governance Parameter for Governance Timelock Duration Itself

Complexity: High (200 points)

Converts hardcoded GOVERNANCE_TIMELOCK_DELAY constant into a governed, adjustable parameter with enforced minimum bounds, allowing protocols to modify
timelock durations as they mature without requiring full contract upgrades.

Changes:

• Type System: Added TimelockDelay variant to ParameterKey enum in shared types
• Storage: Timelock now stored as governed parameter instead of hardcoded constant
• Proposal Structures: Updated Proposal and ParameterProposal structs with timelock_delay field to store original timelock at creation
• Core Functions:
  • get_governance_timelock_delay() - Get current governed timelock with 24-hour default fallback
  • Parameter validation enforces minimum (12 hours = 43,200 seconds) and maximum (90 days = 7,776,000 seconds) bounds
• Initialization: initialize() now sets default timelock parameter (24 hours = 86,400 seconds)
• Parameter Validation: Updated require_valid_parameter() to handle timelock constraints

Key Features:

• In-flight proposals retain their original timelock duration even if parameter changes
• Retroactive parameter changes don't affect already-committed proposals
• Minimum 12-hour bound prevents governance from circumventing security through unreasonably short timelocks
• Applies to both governance module and price_oracle contract
• Allows protocol evolution without contract upgrades

---

Issue #668: On-Chain Audit Trail Dashboard for Executed Governance Proposals

Complexity: High (200 points)

Provides transparent, searchable queryable interface for all executed governance proposals, enabling visibility into "what changed, who voted, when"
without manual proposal ID checking.

Changes:

• Query Functions:
  • get_total_proposal_count() - Get total multisig proposal count for pagination
  • get_total_parameter_proposal_count() - Get total parameter proposal count
  • query_executed_proposals() - Retrieve executed multisig actions with full voting details (paginated, limit 100)
  • query_executed_parameter_proposals() - Retrieve executed parameter changes with governance details
  • query_pending_proposals() - Monitor in-flight governance proposals not yet executed
• Return Format: Full proposal structures including:
  • Proposal ID and action details
  • Proposer address and approval signers
  • Creation and expiration timestamps
  • Execution status and cancellation flags
  • Original timelock (for in-flight proposals)

Key Features:

• Read-only interface with no authorization required
• Pagination support (configurable limit, capped at 100 proposals)
• Suitable for SDK/indexer integration
• Enables dashboard visualization of governance history
• Tracks both multisig proposals and parameter changes
• Shows pending proposals for real-time governance monitoring

---

Technical Details

File Changes

contracts/treasury/src/lib.rs (262 insertions)

• Added revenue-sharing data structures and storage keys
• Implemented distribution lifecycle functions (propose → execute → claim)
• Added helper functions and error types
• Maintains backward compatibility with existing treasury functions

contracts/access_control/src/lib.rs (183 insertions)

• Added Guardian role and emergency pause functions
• Added governance audit trail dashboard queries
• Enhanced parameter management with timelock governance
• Maintains backward compatibility with existing pause/unpause logic

contracts/shared/src/types.rs (5 insertions)

• Added TimelockDelay parameter type
• Added timelock_delay field to Proposal and ParameterProposal structs
• Maintains backward compatibility with existing type system

Error Handling

New Treasury Errors (4):

• NotEligibleStakeholder (16) - Caller not in stakeholder registry
• NoShareAvailable (17) - No claimable share or already claimed
• InvalidDistributionConfig (18) - Invalid distribution configuration
• DistributionProposalNotFound (19) - No pending distribution proposal

New Access Control Errors (2):

• NotGuardian (32) - Caller not assigned Guardian role
• GuardianEmergencyPauseFailed (33) - Emergency pause cannot be triggered

Security Considerations

1. Revenue-Sharing: Comprehensive accounting prevents distribution exceeding available treasury balance
2. Emergency Pause: Guardian role is distinct from admin/multisig to prevent single-point failures
3. Timelock Parameter: Enforced minimum bounds (12 hours) prevent governance from accidentally creating security vulnerabilities
4. Audit Trail: Read-only queries enable transparency without introducing new attack vectors
5. Proposal Snapshots: Original timelock stored on proposals prevents retroactive parameter changes from affecting in-flight governance

Testing Recommendations

• Multi-epoch distribution scenarios with stakeholder roster changes
• Guardian emergency pause followed by governance unpause workflow
• Timelock parameter changes with both pending and executed proposals
• Audit trail queries with various pagination scenarios
• Edge cases: empty stakeholder sets, revoked guardians, expired distributions

---

Compatibility

• ✅ Maintains backward compatibility with existing APIs
• ✅ New storage entries don't conflict with existing keys
• ✅ Non-breaking changes to shared type structures (new fields appended)
• ⚠️ Note: Requires contract reinitialization for new timelock parameter (handled in initialize())

---

Documentation

• Comprehensive docstrings for all new functions
• Parameter bounds and constraints clearly documented
• Error cases and edge conditions explained
• Security patterns documented (fast to pause, slow to unpause)

---

Related Issues

• [High] Implement Treasury Revenue-Sharing Distribution to Fee Stakeholders #667 - Treasury Revenue-Sharing Distribution
• [High] Add an On-Chain Audit Trail Dashboard for Executed Governance Proposals #668 - Governance Audit Trail Dashboard
• [High] Implement Emergency Multi-Role Pause Governance #669 - Emergency Multi-Role Pause Governance
• [High] Add a Governance Parameter for the Governance Timelock Duration Itself #670 - Governance Timelock Duration Parameter

---

Commits

1. 1096675 - Issue [High] Implement Treasury Revenue-Sharing Distribution to Fee Stakeholders #667: Implement Treasury Revenue-Sharing Distribution
2. 61fa075 - Issue [High] Implement Emergency Multi-Role Pause Governance #669: Implement Emergency Multi-Role Pause Governance
3. 3b92969 - Issue [High] Add a Governance Parameter for the Governance Timelock Duration Itself #670: Add Governance Parameter for Timelock Duration
4. b93a4a6 - Issue [High] Add an On-Chain Audit Trail Dashboard for Executed Governance Proposals #668: Add Governance Audit Trail Dashboard

---

[drips-wave]

@Able-faz-system Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits