feat: implement grace period protection for reputation-weighted voting

[OG-wura]

Close #173

Summary

This PR implements a Grace Period for Reputation Updates to prevent last-minute reputation manipulation in the TruthBounty voting system.

Previously, users could artificially increase their voting influence by updating their reputation immediately before participating in claim verification. This change introduces a configurable grace period window that restricts recently updated reputation scores from affecting voting power.

When a reputation update occurs within the configured grace period relative to a claim’s creation timestamp, the voter’s effective reputation defaults to the baseline score instead of using the updated value.

Default grace period: 2 days

---

Problem

Users were able to:

1. Create or identify an active claim
2. Boost their reputation score immediately before voting
3. Vote with inflated voting power
4. Manipulate weighted claim outcomes

This created a vulnerability in the reputation-weighted verification model.

---

Solution

Implemented a symmetric grace period window around claim creation:

timeSinceUpdate = |lastReputationUpdateTime - claimCreatedAt|
withinGracePeriod = timeSinceUpdate <= reputationUpdateGracePeriod

Behavior

• Reputation updates within the grace period → use default reputation
• Reputation updates outside the grace period → use actual reputation

This applies independently per voter.

---

Contracts Updated

IReputationOracle.sol

• Added:

  • getLastReputationUpdate(address user)

MockReputationOracle.sol

• Added timestamp tracking for reputation updates

• Added:

  • lastUpdateTimestamp
  • getLastReputationUpdate()

TruthBountyWeighted.sol

• Added grace period configuration constants

• Added:

  • reputationUpdateGracePeriod
  • _getReputationScoreWithGracePeriod()
  • setReputationUpdateGracePeriod()

• Updated vote() to enforce grace period checks

• Added governance events and validation errors

---

Governance Configuration

Defaults

• Default: 2 days
• Minimum: 1 hour
• Maximum: 30 days

Governance Setter

setReputationUpdateGracePeriod(uint256 newGracePeriod)

---

Testing

Unit Tests

Added comprehensive unit coverage for:

• Grace period configuration
• Last-minute boost prevention
• Reputation window calculations
• Multi-voter scenarios
• Boundary conditions
• Backward compatibility

Invariant Tests

Added Foundry invariants ensuring:

• Grace period enforcement
• Symmetric window behavior
• Independent voter evaluation
• Effective stake integrity
• Governance bounds enforcement

---

Security Impact

Prevented Attacks

• Last-minute reputation boosts
• Coordinated voting manipulation
• Timing-based weighted voting exploits

Guarantees

• Legitimate long-standing reputation remains valid
• Deterministic enforcement
• Governance-controlled but bounded configuration
• Full backward compatibility

---

Backward Compatibility

This implementation maintains backward compatibility through graceful degradation using try/catch for oracle implementations that do not yet support reputation update timestamps.

Existing integrations remain functional.

---

Performance Impact

• Minimal gas overhead (1–2 additional oracle reads per vote)
• Negligible storage increase
• No impact on settlement flow scalability

---

Test Commands

npx hardhat test test/ReputationGracePeriod.test.ts

forge test test/invariant/ReputationGracePeriodInvariant.t.sol -v

npm run test