Feature/issues 663 664 665 666

[soma-enyi]

Summary

This comprehensive pull request implements four interconnected governance enhancements to the Kora protocol, focusing on securing treasury operations, formalizing verifier lifecycle management, implementing stake-weighted reputation systems, and enabling multisig self-governance. All changes ensure that critical protocol operations are subject to rigorous governance controls with appropriate timelocks and multisig approval thresholds.

Issues Addressed

Issue #663: Timelocked Multi-Sig Withdrawal Flow for Treasury

Treasury fee withdrawals are now protected by a 24-hour timelock governance flow, ensuring that fund movements require both multisig quorum approval and a cooling-off period.

Changes:

• Added TREASURY_GOVERNANCE_TIMELOCK_DELAY constant (24 hours) in treasury contract
• Updated execute_treasury_action to enforce governance timelock before execution
• Withdrawal execution now requires: (1) multisig threshold met, (2) 24h timelock elapsed, (3) proposal not expired
• Mirrors access_control's parameter governance timelock pattern for consistency
• Provides defense-in-depth: even if a bad actor gains admin access, withdrawals face a 24h delay

Files Modified:

• contracts/treasury/src/lib.rs

Security Impact: HIGH - Adds mandatory cooling-off period for treasury withdrawals, preventing immediate fund theft even if single admin compromised.

---

Issue #664: Extend Governance to Support Verifier Onboarding/Removal Proposals

Verifier trust is critical to accurate risk scoring. Verifier lifecycle changes (onboarding and removal) now require formal governance proposals, matching the rigor applied to protocol parameter changes.

Changes:

• Added VerifierAction enum: OnboardVerifier(Address) and RemoveVerifier(Address) variants
• Created VerifierProposal struct with full governance tracking (proposer, approvals, timelock state)
• Implemented three governance functions:
  • propose_verifier_action: Initiate verifier management proposals (multisig signers only)
  • vote_verifier_action: Cast signer votes on pending proposals
  • execute_verifier_action: Execute proposals after quorum + timelock requirements met
• Integrated with existing multisig signer set (access_control contract)
• Uses standard GOVERNANCE_TIMELOCK_DELAY (24 hours) for consistency
• Supports both verifier addition and removal with same governance flow
• Added audit trail entries for all verifier governance actions

Files Modified:

• contracts/shared/src/types.rs (VerifierAction enum, VerifierProposal struct)
• contracts/access_control/src/lib.rs (governance functions, storage keys)
• contracts/shared/src/audit.rs (audit action types)

Security Impact: HIGH - Verifier trust is now formally governed; no single admin can unilaterally add/remove verifiers. Handles edge case of removing verifiers with pending submissions (governance must be explicit about consequences).

---

Issue #665: Implement Stake-Weighted Verifier Reputation System

Verifiers now have a reputation score (0–100) that reflects their historical accuracy. Reputation improves slowly with correct assessments but degrades quickly with defaults, incentivizing accuracy and penalizing errors.

Changes:

• Verified existing infrastructure: verifier stakes, reputation tracking, minimum stake requirements
• Added record_successful_repayment(admin, sme) function to reward accurate risk assessments
• Reputation mechanics:
  • Starts at 100 when verifier is onboarded
  • Increments by +1 per successfully repaid invoice (slow recovery, rewards accuracy)
  • Decrements by -10 per recorded default (fast penalty, discourages errors)
  • Capped at 0–100 range (floors at 0, ceils at 100)
• Existing public query function get_verifier_reputation provides read access
• Stake amounts also tracked and slashed on defaults
• Asymmetric penalty/reward structure incentivizes precision in risk scoring

Files Modified:

• contracts/risk_registry/src/lib.rs

Security Impact: MEDIUM - Reputation system prevents bad-faith verifiers from maintaining credibility indefinitely. Investors and protocol can differentiate verifier quality via on-chain reputation. Slashing mechanism still governed separately.

---

Issue #666: Add Governance Proposal for Adjusting the Multisig Signer Set and Threshold

Meta-governance: the multisig itself can now be reconfigured through formal proposals, preventing backdoor control changes and ensuring signer set modifications are as rigorously vetted as protocol parameters.

Changes:

• Added SignerSetProposal struct with extended governance semantics
• Created three meta-governance functions:
  • propose_signer_set_change(new_signers, new_threshold): Propose multisig changes (signers only)
  • vote_signer_set_change(proposal_id): Cast signer votes on pending proposals
  • execute_signer_set_change(proposal_id): Execute after quorum + extended timelock
• Implemented extended SIGNER_SET_GOVERNANCE_TIMELOCK_DELAY (7 days) for extra security
  • Standard governance uses 24h timelock; signer set changes use 7 days
  • Rationale: multisig changes are higher-risk; longer cooling-off period prevents hasty control shifts
• New signer set only activates after timelock expires, not on execution timestamp
• Requires multisig threshold for execution (meta-governance consistency)
• Added full audit trail and event support
• Getter function get_signer_set_proposal for transparency

Files Modified:

• contracts/shared/src/types.rs (SignerSetProposal struct)
• contracts/access_control/src/lib.rs (meta-governance functions, storage keys, constant)
• contracts/shared/src/audit.rs (audit action types)

Security Impact: CRITICAL - Prevents unilateral control changes. Even if a threshold of signers collude, their changes face a 7-day delay, giving the honest signer set time to detect and respond. Recursive governance: the protocol's own control mechanisms are now subject to governance.

---

Integration & Governance Consistency

All four features follow the same governance patterns:

Feature	Proposal Type	Gating	Timelock	Quorum Required
#663 Treasury Withdrawal	TreasuryAction::Withdraw	Multisig signers	24h	Yes (B2)
#664 Verifier Management	VerifierAction	Multisig signers	24h	Yes (B2)
#665 Reputation Tracking	N/A (admin-triggered)	Admin only	None	No
#666 Signer Set Changes	SignerSetProposal	Multisig signers	7d (extended)	Yes (B2)

Governance flow consistency:

1. Proposer must be a configured multisig signer
2. Proposer's vote is automatically recorded
3. Other signers vote using vote_* functions
4. Execution requires: threshold met + timelock elapsed + proposal not expired
5. Full audit trail recorded for compliance

---

Testing Recommendations

For Treasury Withdrawal Timelock (#663)

• Verify proposal creation and voting succeeds
• Verify execution fails if timelock not elapsed (error: GovernanceTimelockNotElapsed)
• Verify execution succeeds after timelock + quorum
• Verify expired proposals cannot execute

For Verifier Governance (#664)

• Test proposing verifier onboarding
• Test proposing verifier removal
• Test voting flow with multiple signers
• Test execution after timelock
• Verify audit trail contains governance actions

For Reputation System (#665)

• Verify new verifiers start at reputation 100
• Verify defaults decrement reputation by 10 (minimum floor 0)
• Verify successful repayments increment reputation by 1 (maximum ceiling 100)
• Test with multiple verifiers concurrently
• Verify get_verifier_reputation returns correct values

For Multisig Governance (#666)

• Test proposing new signer set with different threshold
• Verify extended 7-day timelock is enforced
• Verify new signer set activates after timelock (old signers can't execute in interim)
• Test edge cases: threshold > signer count (must fail)
• Verify audit entries recorded

---

Breaking Changes

None. All changes are additive:

• Treasury withdrawal governance functions already existed; we only added timelock
• Verifier governance is new but doesn't affect existing verifier registration (add_verifier unchanged)
• Reputation tracking already existed; we added the success-case reward mechanism
• Signer set governance is new and doesn't affect existing multisig operations

---

Files Modified

• contracts/treasury/src/lib.rs - Add timelock to execute_treasury_action
• contracts/access_control/src/lib.rs - Add verifier + signer set governance functions
• contracts/shared/src/types.rs - Add VerifierAction, VerifierProposal, SignerSetProposal structs
• contracts/shared/src/audit.rs - Add audit action types

---

Deployment Checklist

• All unit tests pass
• Integration tests for governance flows pass
• Verify timelock constants are correctly set (24h for standard, 7d for meta-governance)
• Audit trail implementation tested in isolation
• Event emissions verified
• Governance documentation updated
• Admin runbook updated with new proposal types

---

Related Issues

Closes #663
Closes #664
Closes #665
Closes #666

[drips-wave]

@soma-enyi 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