feat(governance): add on-chain governance PoC with token-weighted vot…

[abimbolaalabi]

…ing and integration tests

Introduce a proof-of-concept governance contract that demonstrates a
complete on-chain proposal lifecycle as a potential replacement for the
current multisig-controlled upgrade authority. This implementation is
intentionally experimental and serves to validate the overall governance
architecture before committing to a production roadmap.

The new governance crate implements a proposal → vote → execute workflow
secured by a mock token-weighted quorum, together with comprehensive
integration tests and design documentation.

Governance contract

• Create a new stellar/contracts/governance crate and add it to the
  workspace
• Implement governance contract initialization with configurable voting
  period, quorum, timelock, administrator, and governance token
• Add proposal creation flow with persistent proposal storage and unique
  proposal identifiers
• Implement token-weighted voting supporting both "for" and "against"
  votes
• Record individual vote information to prevent duplicate voting and
  provide vote lookup functionality
• Implement proposal execution after successful voting and timelock
  expiration
• Add proposal cancellation flow for failed proposals and administrative
  intervention
• Expose read APIs for governance configuration, proposal details, and
  recorded votes

Voting and execution rules

• Enforce token-weighted quorum using a mock governance token
• Prevent duplicate voting by tracking voter participation
• Reject votes submitted after the voting window closes
• Reject voting attempts from accounts without voting power
• Require proposals to satisfy quorum before execution
• Reject defeated proposals where opposing votes exceed supporting votes
• Enforce a ledger-based timelock before execution is permitted
• Allow governance execution to forward raw Bytes arguments to target
  contracts

Integration tests

Add comprehensive integration coverage validating both expected behavior
and failure scenarios:

• Verify complete happy path from proposal creation through voting,
  timelock expiration, and successful execution
• Verify proposals failing quorum cannot execute and may be cancelled
• Verify defeated proposals cannot be executed
• Verify duplicate votes are rejected
• Verify votes submitted outside the voting window are rejected
• Verify zero-balance accounts cannot participate in voting
• Verify vote records are stored and retrievable
• Verify administrator cancellation during active voting
• Verify execution before timelock expiration is rejected
• Verify governance configuration is initialized correctly
• Verify contract initialization can only occur once

All governance integration tests pass successfully.

Documentation

Expand GOVERNANCE.md with detailed documentation covering:

• Overall governance architecture and proposal lifecycle
• Design decisions adopted for the PoC
• Alternative approaches considered and intentionally rejected
• Tradeoffs behind quorum calculation, vote weighting, execution model,
  and administrative controls
• Explicit "NOT PRODUCTION READY" disclaimer
• Roadmap describing production hardening steps, including:
  • removing centralized admin privileges
  • snapshot-based voting weights
  • typed proposal actions
  • configurable execution thresholds
  • pausable governance integration
  • multi-token support
  • comprehensive security audit

This commit delivers a fully functional governance proof of concept that
compiles successfully, passes all tests, and documents the architectural
choices required to evaluate an eventual transition from multisig-based
upgrade authority to on-chain governance.

Closes #122

[drips-wave]

@abimbolaalabi 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