perf(staking)+docs(governance): transient reward snapshots and governance constitution (#686)

* perf(staking): transient reward snapshots updated only on withdraw calls

* docs(governance): add constitutional rules for quorum, timelocks, and voting lifecycle

Author: yusuftomilola

contracts/staking/src/reward_snapshots.rs

@@ -0,0 +1,56 @@
+#[derive(Clone, Default)]
+pub struct RewardSnapshot {
+    pub staker: [u8; 32],
+    pub accrued_per_token: u128,
+    pub last_updated_block: u64,
+}
+
+impl RewardSnapshot {
+    pub fn new(staker: [u8; 32]) -> Self {
+        Self { staker, accrued_per_token: 0, last_updated_block: 0 }
+    }
+
+    pub fn pending(&self, global_accrued: u128, staked: u128) -> u128 {
+        global_accrued
+            .saturating_sub(self.accrued_per_token)
+            .saturating_mul(staked)
+            .saturating_div(1_000_000_000)
+    }
+
+    pub fn flush(&mut self, global_accrued: u128, block: u64) {
+        self.accrued_per_token = global_accrued;
+        self.last_updated_block = block;
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    const S: [u8; 32] = [1u8; 32];
+
+    #[test]
+    fn pending_before_flush_is_positive() {
+        let snap = RewardSnapshot { staker: S, accrued_per_token: 0, last_updated_block: 0 };
+        assert!(snap.pending(500_000_000, 2_000_000_000) > 0);
+    }
+
+    #[test]
+    fn no_pending_after_flush() {
+        let mut snap = RewardSnapshot::new(S);
+        snap.flush(500_000_000, 100);
+        assert_eq!(snap.pending(500_000_000, 1_000_000_000), 0);
+    }
+
+    #[test]
+    fn rewards_accumulate_between_flushes() {
+        let mut snap = RewardSnapshot::new(S);
+        snap.flush(100_000_000, 1);
+        assert!(snap.pending(200_000_000, 1_000_000_000) > 0);
+    }
+
+    #[test]
+    fn zero_stake_yields_no_pending() {
+        let snap = RewardSnapshot::new(S);
+        assert_eq!(snap.pending(1_000_000_000, 0), 0);
+    }
+}

docs/governance-constitution.md

@@ -0,0 +1,36 @@
+# Governance Constitution
+
+## Quorum & Voting Period
+
+| Parameter          | Value                              |
+|--------------------|------------------------------------|
+| Quorum             | 10% of total voting power          |
+| Voting Period      | 28,800 blocks (~2 days at 6s/block)|
+| Approval Threshold | >50% of votes cast                 |
+
+## Timelocks
+
+| Proposal Type    | Minimum Timelock |
+|------------------|-----------------|
+| Parameter Change | 1 day           |
+| Fund Release     | 2 days          |
+| Emergency Pause  | 0 (immediate)   |
+
+## Proposal Lifecycle
+
+1. **Creation** — Staker with ≥1% of supply submits proposal; voting power snapshotted at this block.
+2. **Voting** — Open for the voting period; only snapshot-block balances count.
+3. **Quorum Check** — Participation must reach 10% before voting closes.
+4. **Timelock** — Approved proposals wait the configured timelock before execution.
+5. **Execution** — Anyone may trigger execution after timelock expires.
+6. **Rejection** — Proposals failing quorum or threshold are rejected and cannot be re-submitted for 24 hours.
+
+## Emergency Pause
+
+Admin may invoke `emergency_override` to pause immediately. Resumption requires a governance vote with ≥60% approval.
+
+## Edge Case Recovery
+
+- **Stuck proposals**: Admin may cancel proposals open > 30 days with zero participation.
+- **Delegate unavailability**: Delegators may reclaim voting power at any block before voting closes.
+- **Quorum failure**: Proposal may be resubmitted after a 24-hour cooldown.