HybridVoting: async-majority early-close (Proposal #60, task #441)

[hudsonhrh]

What this PR does

Two bundled changes to HybridVoting:

1. Configurable early-close turnout gate (closes Argus task #441, Proposal Add DirectDemocracyVoting contract documentation #60). Adds a turnout-percent gate that lets announceWinner fire before the timer expires once enough eligible voters have weighed in. The percent is org-configurable (default 100 = wait for everyone) and per-proposal overridable.

2. CEI re-ordering in vote() (closes Argus task #516). Moves p.hasVoted = true before the external IERC20.balanceOf call in _calculateClassPower — defense-in-depth for future class strategies that might use non-view external calls on cls.asset.

Without (1), every unanimous-mid-window proposal has to wait for its full timer before announce. With it, announceWinner can fire as soon as voterCount ≥ ⌈snapshotEligibleVoters × effectivePct / 100⌉ (the org's chosen turnout threshold). The original timer remains as the fallback.

Why configurable turnout (not a hardcoded gate)

The first design of this feature used ceil(N/2) + strict-majority as the gate, which had a real disenfranchisement risk: half the eligible voters could be cut off by a fast majority. In small orgs that means one or two voices entirely silenced. The redesigned gate is purely turnout-based and lets each org choose its own deliberation/speed tradeoff:

• 100% (default for new orgs): every eligible voter must vote before early-close fires. No risk of cutting anyone off; the timer remains the cap.
• 51-99%: bigger orgs that want fast closes on clear consensus opt down.
• Per-proposal override: a sensitive proposal (constitutional change, large treasury move) can ratchet UP to a stricter floor than the org default — never DOWN.

announceWinner's existing pickWinnerNSlices logic remains the validity arbiter — the gate is permission to attempt announce, not a guarantee of validity. If turnout is reached but no option meets thresholdPct/strict margin, announceWinner returns (0, false) instead of locking in an outcome.

Three create variants

1. createProposal — default. Uses the org's earlyCloseTurnoutPct. This is what every existing caller wants and gets configurable early-close for free.

2. createProposalWithEligibleSnapshot(callerEligibleHint) — caller wants a HIGHER eligibility-snapshot floor than on-chain truth would produce. The contract stores max(callerHint, on-chain hatSupply sum) so under-count is impossible by construction.

   Special sentinel: passing callerEligibleHint = type(uint64).max opts the proposal out of early-close entirely — it must run its full timer regardless of how many voters participate. Use this for proposals where the duration is the policy (RFC windows, mandatory deliberation periods, externally-coordinated timing). The dedicated createProposalLegacyTimerOnly function from the earlier design was removed to save ~670 bytes of runtime bytecode; behavior is preserved via the sentinel.

3. createProposalWithTurnoutPct(pct) — caller wants a HIGHER turnout-percent floor than the org default. Validated pct >= orgDefault && pct <= 100. Used for sensitive proposals where the proposer wants stricter participation than the org's normal threshold.

The reason these are three named functions (instead of one with flags) is that the safety property — "callers can ratchet UP, never DOWN" — is easier to audit when each intent has its own entry point.

Why an under-count guard (eligibility hint)

The original snapshot-hint design accepted a caller-supplied count directly. That breaks the protocol invariant: if a caller passes snapshotEligibleVoters = 2 while 3 addresses actually wear the eligible hats, then ⌈2 × pct / 100⌉ < 3 for any pct ≤ 100 — i.e., a minority of actual eligible voters could trigger early-close. The break is intent-independent (an honest caller using a stale off-chain count produces the same outcome as a malicious caller).

Fix: the contract reads IHats.hatSupply for each eligible hat at create time and clamps the snapshot to max(callerHint, onChainSum). Over-counting (caller raises the threshold) is allowed and conservative. Under-counting (caller lowers the threshold below on-chain truth) is impossible because the on-chain sum is the floor.

Cost: one hatSupply SLOAD per eligible hat at create time (~2.4k gas each, paid once). For typical 1-3 creator hats this is well under 10k gas. vote and announceWinner are unaffected.

What stays the same

• createProposal and vote external signatures unchanged.
• announceWinner external signature unchanged.
• Storage layout: purely additive at struct tails.
  • Proposal gains uint32 voterCount, uint64 snapshotEligibleVoters, uint8 turnoutPctOverride — all packing with the existing bool executed into one trailing slot (14 of 32 bytes used).
  • Layout gains uint8 earlyCloseTurnoutPct — packs into the slot with quorum.
  • Zero new dedicated storage slots beyond those.
• Legacy proposals (created before this upgrade) have snapshotEligibleVoters == 0 (zero-init for new fields). The gate short-circuits to false on zero, so they fall back to the timer path. Verified by test_EarlyClose_legacyBackCompat_zeroSnapshot_timerOnly which uses vm.store to simulate a pre-upgrade proposal.
• Existing orgs upgrading have earlyCloseTurnoutPct == 0 in storage. The gate reads 0 as 100 — the safest default — so existing orgs are MORE strict by default after the upgrade, not less. Executors can call setConfig(EARLY_CLOSE_TURNOUT_PCT, abi.encode(pct)) post-upgrade to opt the org into a looser threshold via governance.
• type(uint64).max remains the unique opt-out sentinel for snapshotEligibleVoters. Overflow in _eligibleVotersUpperBound clamps to type(uint64).max - 1 so on-chain sums can never collide with the sentinel.

Threading through OrgDeployer

The per-org default flows from caller config all the way through to HybridVoting.initialize:

OrgDeployer.DeploymentParams.hybridEarlyCloseTurnoutPct
  → GovernanceFactory.GovernanceParams.hybridEarlyCloseTurnoutPct
  → ModuleDeploymentLib.deployHybridVoting(..., earlyCloseTurnoutPct, ...)
  → HybridVoting.initialize(..., earlyCloseTurnoutPct_, ...)

HybridVoting.initialize validates 1 ≤ earlyCloseTurnoutPct_ ≤ 100 and reverts with InvalidTurnoutPct otherwise. Emits EarlyCloseTurnoutPctSet(pct).

New / changed external surface

// new param at position 6:
function initialize(
    address hats_,
    address executor_,
    uint256[] initialCreatorHats,
    address[] initialTargets,
    uint8 thresholdPct,
    uint8 earlyCloseTurnoutPct,   // <-- NEW
    ClassConfig[] initialClasses
) external;

// new create variants:
function createProposalWithEligibleSnapshot(...) external;       // existing
function createProposalWithTurnoutPct(...) external;             // NEW

// new view helpers:
function earlyCloseTurnoutPct() external view returns (uint8);
function proposalTurnoutPct(uint256 id) external view returns (uint8);
function isEarlyCloseEligible(uint256 id) external view returns (bool);  // existing

// new ConfigKey enum entry for setConfig:
enum ConfigKey {
    THRESHOLD,
    TARGET_ALLOWED,
    EXECUTOR,
    QUORUM,
    EARLY_CLOSE_TURNOUT_PCT       // <-- NEW
}

// new events:
event EarlyCloseTurnoutPctSet(uint8 pct);
event ProposalEarlyCloseConfig(
    uint256 indexed id,
    uint64 snapshotEligibleVoters,
    uint8 turnoutPctOverride,
    bool isTimerOnly
);

Subgraph discoverability

A single ProposalEarlyCloseConfig event fires once per proposal creation regardless of which variant the caller used. Indexers can subscribe to:

• EarlyCloseTurnoutPctSet(pct) on every HybridVoting proxy → track per-org default (fires from initialize at deploy time, and from setConfig later)
• ProposalEarlyCloseConfig(id, snapshot, override, isTimerOnly) → track per-proposal config

The subgraph can compute the effective threshold per proposal without on-chain reads:

effectivePct = turnoutPctOverride != 0 ? turnoutPctOverride : org.hybridEarlyCloseTurnoutPct
threshold = ceil(snapshot × effectivePct / 100)

Subgraph integration is tracked at poa-box/subgraph-pop#178. Frontend wiring at poa-box/Poa-frontend#403. Both repos will pull the new ABI from this branch.

CEI fix in vote() (bundled, task #516)

HybridVotingCore.vote() now sets p.hasVoted[voter] = true before calling IERC20(cls.asset).balanceOf(voter). The originally-cited balanceOf-callback attack is NOT exploitable today — Solidity emits STATICCALL for view functions through interfaces, and the EVM enforces no-state-modification on the entire static-call subtree. CEI re-ordering is forward-defense against future class strategies that might use non-view external calls. The test file HybridVotingReentrancy.t.sol honestly documents this (replacing the original test that claimed to demonstrate reentry prevention but actually passed for an unrelated reason).

Test coverage

test/HybridVotingEarlyClose.t.sol — 41 tests in three groups:

Group A — original PR coverage (14 tests): the 8 scenarios from the trilateral design + 6 robustness scenarios.

Group B — supplementary coverage (12 tests): pause blocks announce, snapshot frozen at create time, batch execution under early-close, threshold=1 single-voter case, out-of-range id safety, empty creatorHats fallback, gate-stays-eligible behavior, callerHint boundary cases.

Group C — new gate semantics (15 tests):

• turnoutPct100_requiresFullTurnout — the new safe default
• turnoutPct51_fires_onMajorityTurnout — looser threshold
• setConfigUpdatesTurnoutPct + setConfigRejectsInvalidPct + setConfigOnlyExecutor — executor-driven updates
• perProposalOverride_ratchetsUp — override ratchet
• overrideRejectedBelowOrgDefault + overrideRejectedAbove100 — validation
• overrideEqualsOrgDefault_ok — boundary
• initializeRejectsInvalidPct — init validation
• eventEmittedOnCreateProposal / …WithEligibleSnapshot / …LegacyTimerOnly (sentinel) / …WithTurnoutPct — ProposalEarlyCloseConfig event verified for each entry point
• thresholdMetButTied_announceReturnsInvalid — gate fires, announceWinner returns invalid (new turnout-only semantics)
• threeOptionEqualSplit_gateFires_announceInvalid — same pattern with 3 options
• gateStaysEligibleOnTie_announceInvalidates — replaces old "gate revokes on tie" test

test/HybridVotingReentrancy.t.sol — 2 CEI ordering property tests (honest framing, no false attack claims).

Full suite: 1351 / 1351 passing. forge fmt clean. Storage layout purely additive vs upgrades/baseline.

Upgrade script + simulation

script/upgrades/UpgradeHybridVotingV11.s.sol ships a 3-step + 1-sim pattern matching UpgradeVotingSelfTarget.s.sol:

# 0. Sim against Arbitrum mainnet fork (CLAUDE.md mandate: simulate before broadcast)
source .env && FOUNDRY_PROFILE=production forge script \
  script/upgrades/UpgradeHybridVotingV11.s.sol:SimulateHybridVotingV11Upgrade \
  --rpc-url arbitrum -vvv

# 1. Deploy impl on Gnosis via DeterministicDeployer
source .env && FOUNDRY_PROFILE=production forge script \
  script/upgrades/UpgradeHybridVotingV11.s.sol:Step1_DeployOnGnosis \
  --rpc-url gnosis --broadcast --slow --private-key $DEPLOYER_PRIVATE_KEY

# 2. Deploy impl on Arbitrum + cross-chain beacon upgrade
source .env && FOUNDRY_PROFILE=production forge script \
  script/upgrades/UpgradeHybridVotingV11.s.sol:Step2_UpgradeFromArbitrum \
  --rpc-url arbitrum --broadcast --slow --private-key $DEPLOYER_PRIVATE_KEY

# 3. Verify Gnosis after ~5 min Hyperlane relay
FOUNDRY_PROFILE=production forge script \
  script/upgrades/UpgradeHybridVotingV11.s.sol:Step3_Verify \
  --rpc-url gnosis

Sim passes end-to-end on Arbitrum fork: pre/post-upgrade state read, v11 impl deployed via DD, beacon upgrade applied under Hudson's prank, KUBI proxy reads the new impl, isEarlyCloseEligible correctly returns false for out-of-range ids, end-to-end create+vote+announce works, and the turnout gate fires correctly on a unanimous single-voter vote.

Notes for review

• MockHats previously hardcoded hatSupply to return 0. This PR adds a hatSupplies counter maintained across mintHat / setHatWearerStatus / renounceHat / transferHat. No existing test exercised hatSupply, so the change is purely additive behavior.
• HybridVotingProposals._eligibleVotersUpperBound is split into Calldata and Storage variants to avoid a redundant calldata→memory copy on the unrestricted branch.
• HybridVoting.MIN_DURATION is bumped from 1 to 10 to match the library constant that's actually enforced. Resolves a pre-existing inconsistency.
• The CEI fix is bundled (originally a separate Argus task #516). PR author had offered to split; keeping bundled because the test rewrite is intertwined with HybridVoting test infrastructure.

Open question for reviewer

The current restricted-poll snapshot uses the pollHatIds passed to createProposal literally, including duplicates. If a proposer accidentally passes the same hat twice, the snapshot double-counts. Adding a dedup pass would cost more memory but tighten the invariant. Worth doing now or defer? Lean: defer — over-count is the safe direction (raises the threshold, makes early-close harder) and the hatIds arg is already author-controlled.

🤖 Generated with Claude Code