@pickhooks/mode-kit 0.0.0-stage → 0.1.0

package/template/mode.json

@@ -0,0 +1,26 @@
+{
+  "kit": 1,
+  "name": "hour",
+  "title": "first of the hour",
+  "contract": "HourMode",
+  "line": "The first buy of every hour wins from the pot.",
+  "how": [
+    "A share of every buy (2 % by default) fills the pot.",
+    "The first buy of at least the minimum size in each UTC hour gets 5 % of the pot.",
+    "A win is never more coins than the winning buy itself brings, and never goes to the creator."
+  ],
+  "share": "bps",
+  "settings": [
+    { "key": "bps", "type": "uint256", "label": "Share of every buy into the pot", "unit": "bps", "default": 200, "min": 100, "max": 300 },
+    { "key": "minPpm", "type": "uint256", "label": "Smallest buy that counts", "unit": "ppm", "default": 100, "min": 10, "max": 1000 }
+  ],
+  "actions": [],
+  "pokes": [],
+  "drand": false,
+  "custody": false,
+  "keeper": null,
+  "notes": [
+    "A bot can wait for the hour to turn and buy first. It wins at most what its own buy brings, and the pot only pays 5 % an hour."
+  ],
+  "author": { "wallet": "", "x": "", "telegram": "" }
+}

package/template/remappings.txt

@@ -0,0 +1,2 @@
+forge-std/=lib/forge-std/src/
+pickhooks/=lib/pickhooks/

package/template/src/HourMode.sol

@@ -0,0 +1,70 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.28;
+
+import {ModeBase} from "pickhooks/ModeBase.sol";
+import {Orders} from "pickhooks/IStickyMode.sol";
+
+/// @title first of the hour: the mode kit's example, a whole mode in one file
+/// @notice The first buy of at least the minimum size in each UTC hour gets 5 % of the game pot, at most what the buy
+///         itself brings, never the creator. A share of every buy (2 % by default) fills the pot.
+/// @dev A template to copy: settings with bounds (quote, _register), state per coin, one rule in _trade, an order back.
+///      Everything a mode returns is checked by the coin: it can only pay out of the game pot, hold coins for at most 7
+///      days, burn, or move held coins; it never touches sells or sends, and if it reverts, runs out of gas or answers
+///      garbage, the coin skips it and the trade goes through.
+contract HourMode is ModeBase {
+    using Orders for Orders.List;
+
+    uint256 public constant SHARE_BPS = 500; // of the pot for the first buy of the hour
+
+    struct Game {
+        uint16 bps; // share of every buy into the pot
+        uint32 minPpm; // the smallest buy that counts, millionths of the supply
+        uint32 hour; // the last hour that had its first buy
+        uint32 wins;
+    }
+
+    mapping(address => Game) public games;
+
+    event FirstOfTheHour(address indexed coin, address indexed buyer, uint32 hour, uint256 paid);
+
+    constructor(address factory_) ModeBase(factory_) {}
+
+    function name() external pure returns (string memory) {
+        return "first of the hour";
+    }
+
+    /// @notice Settings: abi.encode(bps, minPpm), zero for the default. bps 100 to 300 (default 200), minPpm 10 to 1000.
+    ///         The factory asks quote() at launch: the share of buys this mode takes (the validator caps rules + game at 10 %).
+    function quote(address, bytes calldata data) external pure returns (uint16) {
+        (uint256 bps,) = _settings(data);
+        return uint16(bps);
+    }
+
+    function _settings(bytes calldata data) internal pure returns (uint256 bps, uint256 minPpm) {
+        if (data.length != 0) (bps, minPpm) = abi.decode(data, (uint256, uint256));
+        bps = _within(bps, 200, 100, 300, "bps");
+        minPpm = _within(minPpm, 100, 10, 1000, "min");
+    }
+
+    function _register(address coin, address, bytes calldata data) internal override {
+        (uint256 bps, uint256 minPpm) = _settings(data);
+        games[coin] = Game(uint16(bps), uint32(minPpm), 0, 0);
+    }
+
+    function _trade(address coin, Trade calldata t) internal override returns (uint256[] memory) {
+        if (t.kind != BUY) return Orders.none();
+        Game storage g = games[coin];
+        if (_ppm(t.amount) < g.minPpm) return Orders.none();
+        uint32 hour = uint32(block.timestamp / 1 hours);
+        if (hour == g.hour) return Orders.none();
+        g.hour = hour;
+        if (!_player(coin, t.who)) return Orders.none(); // the creator's buy takes the hour and wins nothing
+        uint256 paid = _min(t.pot * SHARE_BPS / 10_000, t.got);
+        if (paid == 0) return Orders.none();
+        g.wins++;
+        emit FirstOfTheHour(coin, t.who, hour, paid);
+        Orders.List memory l = Orders.list(1);
+        l.pay(t.who, paid);
+        return l.done();
+    }
+}

package/template/test/HourMode.t.sol

@@ -0,0 +1,79 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.28;
+
+import {ModeHarness} from "pickhooks/harness/ModeHarness.sol";
+import {Live} from "pickhooks/harness/Live.sol";
+import {HourMode} from "../src/HourMode.sol";
+
+/// Runs on a BNB Chain fork against the live factory and the live coin code: `pickhooks-mode test`.
+contract HourModeTest is ModeHarness {
+    function deployMode() internal override returns (address) {
+        return address(new HourMode(Live.FACTORY));
+    }
+
+    // ------------------------------------------------ the guardrails: the defaults and the edge of every setting
+
+    function test_guardrails_defaults() public {
+        guardrails("");
+    }
+
+    function test_guardrails_low() public {
+        guardrails(abi.encode(uint256(100), uint256(10)));
+    }
+
+    function test_guardrails_high() public {
+        guardrails(abi.encode(uint256(300), uint256(1000)));
+    }
+
+    function test_stress() public {
+        stress("", 60);
+    }
+
+    // ------------------------------------------------ every bound: quote() refuses what is outside it
+
+    function test_bounds() public {
+        expectLaunchRevert(abi.encode(uint256(99), uint256(0)));
+        expectLaunchRevert(abi.encode(uint256(301), uint256(0)));
+        expectLaunchRevert(abi.encode(uint256(0), uint256(9)));
+        expectLaunchRevert(abi.encode(uint256(0), uint256(1001)));
+    }
+
+    // ------------------------------------------------ the rule itself
+
+    function test_firstBuyOfTheHourWins() public {
+        launch("");
+        curveBuy(alice, bps(20)); // fills the pot and takes this hour (an empty pot pays nothing)
+        curveBuy(bob, bps(20)); // the same hour: nothing
+        wait(1 hours);
+        uint256 pot = coin.gamePot();
+        uint256 before = coin.balanceOf(carol);
+        curveBuy(carol, bps(20));
+        uint256 got = bps(20) * 9800 / 10_000; // 2 % of the buy goes into the pot
+        uint256 potWith = pot + bps(20) * 200 / 10_000;
+        assertEq(coin.balanceOf(carol) - before, got + potWith * 500 / 10_000, "5 % of the pot to the first buy of the hour");
+    }
+
+    function test_creatorTakesTheHourAndWinsNothing() public {
+        launch("");
+        curveBuy(alice, bps(50));
+        wait(1 hours);
+        uint256 pot = coin.gamePot();
+        curveBuy(dev, bps(10));
+        assertEq(coin.gamePot(), pot + bps(10) * 200 / 10_000, "the creator wins nothing");
+        uint256 b = coin.balanceOf(bob);
+        curveBuy(bob, bps(10)); // the hour is taken
+        assertEq(coin.balanceOf(bob) - b, bps(10) * 9800 / 10_000);
+    }
+
+    function test_smallBuysDoNotTakeTheHour() public {
+        launch("");
+        curveBuy(alice, bps(20));
+        wait(1 hours);
+        uint256 b = coin.balanceOf(bob);
+        curveBuy(bob, ppm(50)); // under the minimum of 100 millionths: no win, the hour stays open
+        assertEq(coin.balanceOf(bob) - b, ppm(50) * 9800 / 10_000);
+        uint256 c = coin.balanceOf(carol);
+        curveBuy(carol, ppm(200));
+        assertGt(coin.balanceOf(carol) - c, ppm(200) * 9800 / 10_000, "the first buy over the minimum wins");
+    }
+}