feat: Implement governance & treasury features (issues #671-674)

[Barbie-Dev]

Summary

This PR implements four major governance and treasury management features for the Kora Protocol:

• Dispute arbitration governance with multisig gating
• Community proposal submission with cooldown mechanisms
• Treasury diversification policy contract with drift detection
• Governance-gated risk tier definitions with version-locking

All features integrate seamlessly with the existing access_control governance infrastructure and include comprehensive error handling, audit logging, and persistent storage management.

Issues Closed

Closes #671
Closes #672
Closes #673
Closes #674

---

Issue #671: Dispute Arbitration Governance

Objective

Transfer dispute resolution authority from single admin to governance mechanisms, applying multisig + timelock safeguards consistent with other critical protocol functions.

Implementation

• New Action Type: Added ResolveDispute(Address, u64, bool) to AdminAction enum for governance-gated dispute resolution
• Contract Registration: Added DisputeResolution storage key to access_control for tracking dispute resolution contract address
• Admin Function: Implemented set_dispute_resolution() to register the dispute resolution contract
• Execution Handler: Added dispute resolution handling in execute_action() workflow with proper multisig validation
• Documentation: Updated resolve_dispute() comments to clarify governance requirement

Files Modified

• contracts/shared/src/types.rs - Added ResolveDispute action variant
• contracts/access_control/src/lib.rs - Added dispute resolution gating logic
• contracts/dispute_resolution/src/lib.rs - Updated documentation

Key Changes

// Now disputes must be resolved through governance proposals
AdminAction::ResolveDispute(resolver, invoice_id, upheld)

Impact

• Dispute resolution now requires multisig proposal/approval/execution with ~24h timelock
• Prevents single-admin resolution of contested defaults
• Aligns with protocol's approach to other critical functions (upgrades, parameter changes)

---

Issue #672: Community Proposal Submission Threshold and Cooldown

Objective

Expand proposal submission beyond multisig signer group to broader community (accredited investors, verifiable entities) while maintaining signer gatekeeping authority.

Implementation

• Community Proposal Struct: Added CommunityProposal for staging non-signer proposals with submitter context and description
• Storage Keys:
  • CommunityProposal(u64) - staged proposals by ID
  • NextCommunityProposalId - monotonic counter
  • CommunityProposalCooldown(Address) - per-submitter cooldown tracking
• Cooldown Mechanism: Added COMMUNITY_PROPOSAL_COOLDOWN constant (1 day) to prevent spam
• Submission Function: submit_community_proposal() stages proposals with cooldown enforcement
• Retrieval Function: get_community_proposal() for reading staged proposals
• Sponsorship Function: sponsor_community_proposal() allows signers to elevate proposals to formal governance

Files Modified

• contracts/shared/src/types.rs - Added CommunityProposal struct
• contracts/access_control/src/lib.rs - Added community proposal infrastructure

Key Features

• Per-submitter cooldown prevents spam while enabling regular participation
• Signers retain gatekeeping control over formal proposal introduction
• Community proposals converted to formal multisig proposals on sponsorship
• Proposer's vote automatically recorded on sponsorship

Impact

• Democratizes governance by enabling broader community participation
• Maintains security through signer-required sponsorship gate
• Cooldown bypass possible through multiple addresses (documented limitation)

---

Issue #673: Treasury Diversification Policy Contract

Objective

Establish and enforce target asset allocation ranges for treasury holdings to prevent unintended concentration once multi-asset fee collection exists.

Implementation

• Policy Struct: Added AssetAllocationPolicy with min/max allocation targets per asset in basis points
• Drift Detection Struct: Added AllocationDrift for reporting allocation deviations
• Storage Key: AssetAllocationPolicy(Address) for asset-specific policies
• Policy Management: set_asset_allocation_policy() for governance-configurable target ranges
• Policy Retrieval: get_asset_allocation_policy() for reading current policies
• Drift Detection: check_allocation_drift() read-only function identifying when holdings deviate from targets

Files Modified

• contracts/shared/src/types.rs - Added AssetAllocationPolicy and AllocationDrift structs
• contracts/treasury/src/lib.rs - Added allocation policy infrastructure

Key Features

• Read-only drift detection operates in informational capacity only
• No automated rebalancing (future DEX integration phase)
• Supports multiple assets with independent target ranges
• Handles edge cases where policy defines assets not yet acquired

Impact

• Prevents treasury concentration risk as fee collection diversifies
• Provides observable drift alerts without enforcement
• Foundation for future DEX-integrated rebalancing mechanisms

---

Issue #674: Governance-Gated Risk Tier Definitions

Objective

Convert hardcoded risk tier score-to-tier mappings into governed, versioned configuration that evolves with protocol's maturation and real default-rate data.

Implementation

• Versioned Tier Definition: Added RiskTierDefinition struct with:
  • Version counter for governance updates
  • Configurable score boundaries (aaa_max, aa_max, a_max, b_max)
  • Activation timestamp for audit trail
  • score_to_tier() method for tier lookup
• Storage Keys:
  • CurrentRiskTierDefinition - active tier definition
  • RiskTierDefinitionVersion(u32) - historical versions for version-locking
  • RiskTierDefinitionUpdatedAt - last update timestamp
• Default Initialization: Created create_default_risk_tier_definition() with standard boundaries:
  • AAA: 0–20
  • AA: 21–40
  • A: 41–60
  • B: 61–80
  • C: 81–100
• Management Functions:
  • get_current_risk_tier_definition() - retrieve active definition
  • get_risk_tier_definition_version() - retrieve historical versions
  • update_risk_tier_definition() - governance-controlled updates with validation

Files Modified

• contracts/shared/src/types.rs - Added RiskTierDefinition struct with helper method
• contracts/risk_registry/src/lib.rs - Added tier definition management infrastructure

Key Features

• Version-locking ensures in-flight listings remain tied to tier definition active at creation
• Prevents retroactive tier changes affecting existing listings
• Governance-controlled boundary adjustments without contract redeployment
• Comprehensive validation of tier boundary ordering and ranges

Impact

• Tier boundaries now configurable via governance instead of hardcoded constants
• Supports protocol evolution as default-rate data matures
• Enables A8 (dynamic fees) and A17 (tiered amount bounds) to reference authorized definitions
• Maintains audit trail through versioning

---

Technical Highlights

Governance Integration

All features integrate with existing access_control infrastructure:

• Multisig signer validation
• Proposal/approval/execution workflow
• Governance timelock enforcement (~24 hours)
• Comprehensive audit logging with checksums

Storage Management

• Proper TTL management for all persistent storage
• Audit entries logged with sequence numbers and checksums
• Historical data retention for version-locking support
• Idempotent operations where applicable

Error Handling

• Comprehensive error variants for new features
• Validation of all governance parameters
• Safe arithmetic with overflow detection
• Clear error messages for debugging

Testing Ready

• Production-grade error handling
• Storage bounds checking throughout
• Audit trail for all modifications
• Ready for comprehensive test suite integration

---

Files Changed

• contracts/shared/src/types.rs - Added 5 new structs (CommunityProposal, AssetAllocationPolicy, AllocationDrift, RiskTierDefinition, etc.)
• contracts/access_control/src/lib.rs - Added governance infrastructure for disputes and community proposals
• contracts/treasury/src/lib.rs - Added allocation policy management
• contracts/dispute_resolution/src/lib.rs - Updated documentation for governance requirement
• contracts/risk_registry/src/lib.rs - Added versioned tier definition system

Commits

• 2619ce4 - feat([High] Implement Dispute Arbitration Governance for Contested Defaults #671): Implement dispute arbitration governance
• 654e0b6 - feat([High] Add a Community Proposal Submission Threshold and Cooldown #672): Add community proposal submission with cooldown
• 7041cd5 - feat([High] Implement a Treasury Diversification Policy Contract #673): Implement treasury diversification policy contract
• ea548b8 - feat([High] Add Governance-Gated Risk Tier Definitions #674): Implement governance-gated risk tier definitions

Testing Recommendations

1. Unit Tests: Each new function should have comprehensive test coverage
2. Integration Tests: Verify governance workflows across contracts
3. Edge Cases: Test boundary conditions for all policies and definitions
4. Audit Trail: Verify all changes are properly logged
5. Backward Compatibility: Confirm existing functionality unaffected

Checklist

• All code follows existing patterns and conventions
• Comprehensive error handling implemented
• Audit logging added for all changes
• Storage TTL management implemented
• Documentation updated
• Version-locking support for governance changes
• Governance integration complete

[drips-wave]

@Barbie-Dev 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