Hardening before deploy: 5-point weight cap per epoch, freeze valve fix, two-step exit (leave), draw guards, keeper does the full cycle

Author: GraphFunding

.github/workflows/contracts.yml

@@ -1,14 +1,16 @@
 name: contracts
 on: [push, pull_request]
+permissions:
+  contents: read
 jobs:
   test:
     runs-on: ubuntu-latest
     defaults:
       run:
         working-directory: contracts
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
         with:
           submodules: recursive
-      - uses: foundry-rs/foundry-toolchain@v1
+      - uses: foundry-rs/foundry-toolchain@908c540300062bd5a7e473851cdb4282204cee09 # v1.9.1
       - run: forge test -vv

.github/workflows/keeper.yml

@@ -3,21 +3,30 @@ on:
   schedule:
     - cron: "*/15 * * * *"
   workflow_dispatch:
+permissions:
+  contents: read
+# One run at a time: a late cron tick or a manual dispatch waits for the running one instead of racing it on the same
+# draw/advance (or nonce).
+concurrency:
+  group: keeper
+  cancel-in-progress: false
 jobs:
   tick:
     if: ${{ vars.GRAPHFUND_ADDRESS != '' }}
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     defaults:
       run:
         working-directory: ops/keeper
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:
           node-version: 22
-      - run: npm ci --no-audit --no-fund
+      - run: npm ci --ignore-scripts --no-audit --no-fund
       - run: node keeper.mjs
         env:
           RPC_URL: ${{ secrets.RPC_URL }}
           GRAPHFUND_ADDRESS: ${{ vars.GRAPHFUND_ADDRESS }}
           KEEPER_PRIVATE_KEY: ${{ secrets.KEEPER_PRIVATE_KEY }}
+          MIN_BALANCE_ETH: ${{ vars.MIN_BALANCE_ETH }}

README.md

@@ -43,7 +43,8 @@ small committee drawn at random decides how the money splits. Nobody ever votes
 1. **Enlist.** Lock at least 100,000 $GRAPHFUND. Your chance of being drawn is your share of everything locked.
 2. **Drawn.** The hash of a future block picks five Keepers for every fork. Nobody knows who in advance.
 3. **Vote.** Each Keeper proposes how the money below their fork should split. The **median** wins, so one bad vote
-   moves nothing. Voting mints a soulbound Keeper badge.
+   moves nothing, and no share moves more than **5 points per epoch**, so no single committee can hijack a fork.
+   Voting mints a soulbound Keeper badge.
 4. **Flow.** Every six hours the epoch closes and the money climbs down the tree. Keepers who voted on a fork share 2%
    of what flowed through it.
 
@@ -54,7 +55,7 @@ small committee drawn at random decides how the money splits. Nobody ever votes
 ```mermaid
 flowchart LR
     D["draw()<br/>five Keepers per fork,<br/>weighted by stake"] --> V["vote()<br/>each Keeper sends a split<br/>and gets a soulbound badge"]
-    V --> A["advance()<br/>median per fork, money moves down,<br/>2% to the voters, next draw requested"]
+    V --> A["advance()<br/>median per fork (max 5 pts a move),<br/>money moves down, 2% to the voters,<br/>next draw requested"]
     A -- "6 hours later" --> D
 
     classDef step fill:#f3ebdd,stroke:#2b59c3,stroke-width:2px,color:#2b59c3
@@ -83,7 +84,8 @@ escrow **straight into this contract**. Every claim is public on Etherscan. Anyo
 
 <p align="center"><img src="docs/readme/genesis-tree.jpg" alt="The genesis tree: four branches and fourteen recipients" width="100%" /></p>
 
-The starting weights, before any committee has voted. From the first epoch on, the committees decide.
+The starting weights, before any committee has voted. From the first epoch on, the committees decide, 5 points per
+epoch at most.
 
 <table>
   <tr><th align="left">Branch</th><th align="left">Recipient</th><th align="right">Inside the branch</th><th align="right">Of every ETH¹</th></tr>
@@ -111,15 +113,16 @@ The starting weights, before any committee has voted. From the first epoch on, t
 > lives in [contracts/script/genesis.json](contracts/script/genesis.json).
 
 **New projects can join.** Anyone can propose a project under a branch with a deposit of 1,000,000 $GRAPHFUND. It
-enters at 0% and only gets money if a committee gives it weight; the deposit comes back the first time it does.
+enters at 0%, gains at most 5 points per epoch, and only gets money if a committee gives it weight; the deposit comes
+back the first time it does.
 
 <br />
 
 ## Who can do what
 
 | | Can | Cannot |
 |---|---|---|
-| **Keepers** | Lock and unlock $GRAPHFUND, vote on the fork they were drawn for | Unlock while sitting on a committee |
+| **Keepers** | Lock $GRAPHFUND, vote on the fork they were drawn for, leave the draw and unlock | Unlock while sitting on a committee |
 | **Anyone** | Call `draw()` and `advance()`, send ETH, propose a project, trigger `payout` for a recipient | Choose who gets drawn |
 | **Owner** *(until renounced)* | Edit the tree and the starting weights, change parameters within fixed bounds, reject spam proposals | Touch anyone's stake, touch money owed to a project, choose who gets drawn |
 
@@ -132,7 +135,7 @@ The owner renounces after **28 epochs (7 days)** with committees drawn and no em
 | Contract | What it does |
 |---|---|
 | [`GraphFund`](contracts/src/GraphFund.sol) | The tree, the epochs (`draw` → `vote` → `advance`), the payouts (ETH, or WETH to contracts that refuse ETH) and the proposals |
-| [`KeeperStaking`](contracts/src/KeeperStaking.sol) | Lock $GRAPHFUND (minimum 100,000) to enter the draw. Stakes freeze for about a minute while a draw is pending (never more than ~1 day), and stay locked while you sit on a committee |
+| [`KeeperStaking`](contracts/src/KeeperStaking.sol) | Lock $GRAPHFUND (minimum 100,000) to enter the draw. Stakes can't change while a draw is pending (minutes; if nobody draws, anyone can end it with `draw()`), and stay locked while you sit on a committee. To exit: `leave()` takes you out of every future draw, then `unstake` as soon as your seat ends |
 | [`KeeperBadge`](contracts/src/KeeperBadge.sol) | One soulbound token per epoch you voted in |
 | $GRAPHFUND | 1,000,000,000 fixed supply, launched on Stockereum |
 
@@ -143,9 +146,11 @@ Addresses go here, and on the site, the moment they are deployed.
 ## Honest limits
 
 - ⚖️ **Stake buys seats.** Seats are drawn in proportion to what is locked: whoever locks most of the supply wins most
-  seats. The median protects a fork's split only while no one holds three of its five seats. Every seat and every vote
-  is public.
-- 🎲 **Randomness is a future blockhash.** The proposer of that block can bias it by withholding the block.
+  seats. The median protects a fork's split only while no one holds three of its five seats, and even a captured
+  committee moves each share at most 5 points per epoch. Every seat and every vote is public.
+- 🎲 **Randomness is a future blockhash.** Whoever builds that block (a role that can be bought for a single slot) can
+  grind its hash and pick a committee. The 5-point cap is the answer: capturing one committee pays little, and honest
+  committees undo it at the same speed. Verifiable randomness (e.g. a VRF) would close it for good.
 - 🔑 **The fee claim depends on the creator wallet.** Claims into the contract are public, but someone has to make them.
 - ⛽ **One transaction draws every committee.** Parameters are bounded (`committeeSize × maxNodes/2 ≤ 120`) so the worst
   case stays well under Ethereum's per-transaction gas cap.

contracts/src/GraphFund.sol

@@ -14,7 +14,8 @@ import {Median} from "./lib/Median.sol";
 /// @title Graph Funding
 /// @notice Snowmoon, chapter 17, on Ethereum. Fees flow down a tree of public goods. At every branch a
 ///         committee drawn at random from $GRAPHFUND stakers sets the weights of the children.
-/// @dev Unaudited. Randomness comes from the blockhash of a future block, which that block's proposer can bias.
+/// @dev Unaudited. Randomness comes from the blockhash of a future block, which the builder of that block can grind;
+///      `maxShiftBps` caps how far one committee can move any weight per epoch.
 contract GraphFund is Ownable2Step, ReentrancyGuard {
     using SafeERC20 for IERC20;
 
@@ -42,6 +43,7 @@ contract GraphFund is Ownable2Step, ReentrancyGuard {
         uint16 maxNodes;
         uint8 pruneAfter;
         uint256 proposalBond;
+        uint16 maxShiftBps; // max change of a child's weight per epoch (10_000 = no cap)
     }
 
     error BadNode();
@@ -66,6 +68,7 @@ contract GraphFund is Ownable2Step, ReentrancyGuard {
     error NotFunded();
     error BondSettled();
     error NotPrunable();
+    error DrawPending();
 
     event NodeAdded(uint32 indexed id, uint32 indexed parent, address recipient, address proposer, string name, bool pending);
     event NodeActivated(uint32 indexed id);
@@ -134,7 +137,8 @@ contract GraphFund is Ownable2Step, ReentrancyGuard {
             maxDepth: 4,
             maxNodes: 48,
             pruneAfter: 4,
-            proposalBond: 1_000_000e18
+            proposalBond: 1_000_000e18,
+            maxShiftBps: 500
         });
         _nodes.push();
         Node storage root = _nodes[0];
@@ -154,10 +158,12 @@ contract GraphFund is Ownable2Step, ReentrancyGuard {
     // ================================================================ owner: tree & params
 
     function addNode(uint32 parent, string calldata name, address recipient) external onlyOwner returns (uint32) {
+        if (drawPending) revert DrawPending();
         return _create(parent, name, recipient, address(0), 0);
     }
 
     function removeNode(uint32 id) external onlyOwner {
+        if (drawPending) revert DrawPending();
         if (id == 0 || id >= _nodes.length) revert BadNode();
         Node storage n = _nodes[id];
         if (!(n.active || n.pending)) revert BadNode();
@@ -176,11 +182,12 @@ contract GraphFund is Ownable2Step, ReentrancyGuard {
     }
 
     function setParams(Params calldata p) external onlyOwner {
+        if (drawPending) revert DrawPending();
         if (
             p.epochLength < 10 minutes || p.epochLength > 7 days || p.committeeSize == 0 || p.committeeSize > 9
                 || p.voterPayBps > 1_000 || p.drawDelay == 0 || p.drawDelay > 64 || p.maxChildren < 2
                 || p.maxChildren > 16 || p.maxDepth == 0 || p.maxDepth > 6 || p.maxNodes < liveNodes
-                || p.maxNodes > 128 || p.pruneAfter == 0
+                || p.maxNodes > 128 || p.pruneAfter == 0 || p.maxShiftBps < 100 || p.maxShiftBps > 10_000
         ) revert BadParams();
         if (uint256(p.epochLength) < uint256(p.drawDelay) * 12 + 1 hours) revert BadParams(); // voting window after the seed
         if (uint256(p.committeeSize) * (uint256(p.maxNodes) / 2) > 120) revert BadParams(); // keeps draw() far under the 16.78M tx gas cap
@@ -201,7 +208,10 @@ contract GraphFund is Ownable2Step, ReentrancyGuard {
     function draw() external {
         if (!drawPending) revert NoDrawPending();
         if (block.number <= seedBlock) revert TooEarly();
-        if (block.number - seedBlock > 256) {
+        // A stale seed, or one published after the stake freeze expired (stakes could move once it was known),
+        // is never consumed: ask for a new one.
+        if (block.number - seedBlock > 256 || block.number >= staking.drawPendingSince() + staking.FREEZE_MAX()) {
+            staking.setDrawPending(false); // re-arms the freeze before a new seed exists
             _requestDraw();
             return;
         }
@@ -250,10 +260,12 @@ contract GraphFund is Ownable2Step, ReentrancyGuard {
         uint256 e = epoch;
         if (e == 0) revert NotStarted();
         if (block.timestamp < epochStart + _params.epochLength) revert TooEarly();
+        uint256 raw = address(this).balance; // ETH that arrived without receive() (forced sends)
+        if (raw > 0) weth.deposit{value: raw}();
         (uint32[] memory br, uint256 nb) = _activeBranches();
         for (uint256 b; b < nb; b++) _finalize(e, br[b]);
         uint256 distributed = _distribute(e);
-        _updateStreaks(br, nb);
+        _updateStreaks(e, br, nb);
         _activatePending();
         epoch = e + 1;
         epochStart = block.timestamp;
@@ -281,12 +293,14 @@ contract GraphFund is Ownable2Step, ReentrancyGuard {
         if (recipient == address(0)) revert ZeroAddress();
         uint256 bond = _params.proposalBond;
         IERC20 t = _bondToken();
+        if (parent == 0) revert BadParent(); // proposals go under a branch, never straight under the root
         id = _create(parent, name, recipient, msg.sender, bond);
         if (bond > 0) t.safeTransferFrom(msg.sender, address(this), bond);
         emit Proposed(id, msg.sender, bond);
     }
 
     function rejectProposal(uint32 id) external onlyOwner {
+        if (drawPending) revert DrawPending();
         if (id >= _nodes.length) revert BadNode();
         Node storage n = _nodes[id];
         if (n.proposer == address(0) || !(n.active || n.pending)) revert BadNode();
@@ -318,6 +332,7 @@ contract GraphFund is Ownable2Step, ReentrancyGuard {
     }
 
     function prune(uint32 id) external {
+        if (drawPending) revert DrawPending();
         if (id >= _nodes.length) revert BadNode();
         Node storage n = _nodes[id];
         if (n.proposer == address(0) || !n.active || n.zeroStreak < _params.pruneAfter) revert NotPrunable();
@@ -555,14 +570,19 @@ contract GraphFund is Ownable2Step, ReentrancyGuard {
         if (valid == 0) return;
         uint256[] memory med = new uint256[](nk);
         uint16[] memory col = new uint16[](valid);
+        bool any;
         for (uint256 c; c < nk; c++) {
             uint256 j;
             for (uint256 v; v < nv; v++) {
                 if (vs[v].length == nk) col[j++] = vs[v][c];
             }
             med[c] = Median.median(col);
+            if (med[c] > 0) any = true;
         }
+        if (!any) return; // every median is 0: keep the current weights
         uint16[] memory w = Median.normalize(med);
+        uint256 cap = _params.maxShiftBps;
+        if (cap < 10_000) w = Median.step(_weights[id], w, cap);
         _weights[id] = w;
         emit WeightsFinalized(e, id, w);
     }
@@ -607,15 +627,17 @@ contract GraphFund is Ownable2Step, ReentrancyGuard {
         }
     }
 
-    function _updateStreaks(uint32[] memory br, uint256 nb) internal {
+    /// @dev A zero-weight epoch only counts toward pruning when the fork had a committee that voted in epoch `e`.
+    function _updateStreaks(uint256 e, uint32[] memory br, uint256 nb) internal {
         for (uint256 b; b < nb; b++) {
             uint32[] storage ks = _kids[br[b]];
             uint16[] storage ws = _weights[br[b]];
+            bool voted = _voters[e][br[b]].length > 0;
             for (uint256 i; i < ks.length; i++) {
                 Node storage c = _nodes[ks[i]];
                 if (c.proposer == address(0)) continue;
                 if (ws[i] == 0) {
-                    if (c.zeroStreak < type(uint8).max) c.zeroStreak++;
+                    if (voted && c.zeroStreak < type(uint8).max) c.zeroStreak++;
                 } else {
                     c.zeroStreak = 0;
                     c.everFunded = true;

contracts/src/KeeperBadge.sol

@@ -3,10 +3,11 @@ pragma solidity 0.8.26;
 
 import {ERC1155} from "@openzeppelin/contracts/token/ERC1155/ERC1155.sol";
 import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
+import {Ownable2Step} from "@openzeppelin/contracts/access/Ownable2Step.sol";
 
 /// @title Keeper badge
 /// @notice One soulbound token per epoch in which a keeper voted (id = epoch).
-contract KeeperBadge is ERC1155, Ownable {
+contract KeeperBadge is ERC1155, Ownable2Step {
     error Soulbound();
     error NotMinter();
     error AlreadySet();