@pickhooks/mode-kit 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pickhooks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,125 @@
-# Temporary Holding Version
+# @pickhooks/mode-kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Write a game for pickhooks coins. Earn on every coin that plays it.
+
+A **mode** is the game inside a pickhooks coin on BNB Chain: combo, pay it forward, heist, revenge and the ones you
+write. The coin calls its mode after every buy, sell and send, holders play it through the coin, and the coin carries
+out what the mode answers under rules no mode can break. You write one Solidity contract, test it on a BNB Chain fork
+against the live contracts, and send it in. pickhooks reviews it, deploys it and lists it in the launcher.
+
+**What you earn: half of the pickhooks fee of every coin launched with your mode, in BNB, for as long as it trades.**
+It comes out of the pickhooks side. The creator's share is not touched.
+
+```bash
+npx @pickhooks/mode-kit init my-mode --contract MyMode --title "my mode"
+cd my-mode
+echo "BSC_RPC_URL=https://..." > .env      # any BNB Chain RPC
+npx @pickhooks/mode-kit test                  # your mode on the live factory, the live coin code, PancakeSwap's routers
+npx @pickhooks/mode-kit pack                  # check, test, one file for the review
+```
+
+You need Node 20+ and [Foundry](https://getfoundry.sh).
+
+## Why build here
+
+- **A mode cannot break a coin.** The coin checks every order a mode gives. If a mode reverts, runs out of gas or
+  answers garbage, the coin skips it for that trade and the trade goes through. Sells and sends are never taxed.
+- **Every coin trades everywhere from the first second.** GMGN, Binance Wallet, PancakeSwap, any router. Your game
+  reaches every trader, not only the ones on one site.
+- **No fee to submit, no deploy cost.** pickhooks deploys your mode, verified on BscScan. Nobody holds a key to it:
+  a mode is fixed, like the coins that use it.
+- **Tested against what is live.** The harness forks BNB Chain and lists your mode on the real factory, so your tests
+  run the exact coin code and pools your players will trade.
+- **Do not write Solidity?** Tell us the mechanic and we build it with this kit. You are still its author and earn the
+  same share.
+
+## The project
+
+```
+src/MyMode.sol        the mode (it starts as "first of the hour", a whole mode in one file)
+test/MyMode.t.sol     its tests on a fork
+mode.json             what it is, its settings and actions, in the launcher's words
+lib/pickhooks/        the kit: IStickyMode.sol, ModeBase.sol, harness/ (do not edit)
+```
+
+## Commands
+
+Run them as `npx @pickhooks/mode-kit <command>`, or install the kit once (`npm i -g @pickhooks/mode-kit`) and run `pickhooks-mode <command>`.
+
+| command | what it does |
+| --- | --- |
+| `pickhooks-mode init <dir>` | a Foundry project with a working mode, its tests and its mode.json |
+| `pickhooks-mode check` | mode.json, the source and the built bytecode against the rules below |
+| `pickhooks-mode test` | `forge test` on a fork (BSC_RPC_URL in .env) |
+| `pickhooks-mode pack` | check, test, and `submission/<name>-<hash>.json` for the review |
+| `pickhooks-mode encode settings bps=250` | the settings as the factory takes them |
+| `pickhooks-mode encode action try coins=1000` | a holder's play |
+| `pickhooks-mode brief` | a brief for a coding agent: paste it into Claude Code, Cursor or Codex with your idea |
+| `pickhooks-mode addresses` | the live contracts |
+
+## How a mode works
+
+Extend `ModeBase` and implement `name()`, `quote()` (the bounds of your settings and the share of every buy that goes
+into the coin's game pot), `_register()`, `_trade()` (after every buy, sell and send) and, if players act, `_play()`
+and `_poke()`. A mode never moves a coin: it answers with **orders** and the coin carries them out.
+
+| order | what the coin does |
+| --- | --- |
+| `pay(to, amount)` | pays out of the game pot, at most the pot |
+| `payHeld(to, amount, until)` | the same, into custody |
+| `hold(who, to, amount, until, flags)` | a player's own free coins into custody, only in that player's own play |
+| `release(who)` | custody back to the wallet |
+| `burnHeld(who, amount)` | burns coins in custody |
+| `moveHeld(who, to, amount, until)` | moves custody to another holder |
+| `burnPot(amount)` | burns out of the pot |
+| `burn(who, amount)` | burns a player's own free coins, only in that player's own play |
+| `setUntil(who, until)` | moves the end of a custody |
+
+At most 16 orders per answer. Custody ends by itself at most 7 days after it began. Randomness comes from drand
+through the beacon on chain (`pickhooks-mode addresses`), never from block values.
+
+## What the coin holds whatever a mode does
+
+- The mode gets 250,000 gas per trade; the harness wants every trade under 200,000.
+- A failing mode is skipped for that trade and the trade stands. The harness fails on any skip.
+- Sells and sends are never taxed. A buy gives at most 10 % to burns and pots together, the mode's share included.
+- The pot fills only with the mode's share of buys and leaves only by orders: paid to holders or burned.
+- The mode is fixed at launch, for good.
+
+## The harness
+
+`ModeHarness` (lib/pickhooks/harness) forks BNB Chain, lists your mode on the live factory as its owner (on the fork
+only), launches coins and trades them through PancakeSwap's V3 and V2 routers.
+
+- `guardrails(settings)`: buys on every path (one by the creator), sends, sells, an hour apart. Sends and sells take
+  nothing, the coin never skipped the mode, the pot is backed, under 200,000 gas.
+- `stress(settings, n)`: n trades of five wallets, changing sizes and times, the same checks.
+- `expectLaunchRevert(settings)`: the factory refuses settings outside your bounds.
+- `curveBuy`, `curveSell`, `routerBuy`, `routerSell`, `v2Buy`, `v2Sell`, `send`, `play`, `poke`, `wait`, `modeGas`.
+
+## What the review checks
+
+`pickhooks-mode check` enforces the first part: no selfdestruct, delegatecall, payable, low level calls, coin transfers
+or approvals, calls back into the coin, new contracts, owners, proxies or upgrades, no tx.origin, no block values as
+randomness, runtime code under 24,576 bytes, name() equal to the title, notes that say what can be gamed. Then a person
+reads every line against this list:
+
+1. Every setting has bounds; quote() reverts outside them and returns the share of buys.
+2. `_trade` stays well under 250,000 gas in its worst case; loops are bounded.
+3. Nothing in `_trade` can revert on a normal buy, sell or send.
+4. Payouts never go to the creator, a pool, the coin or the dead address, and never more than the trade or the pot
+   justifies.
+5. Custody always has an end the holder can see, never more than 7 days.
+6. A holder's free coins move only in that holder's own play.
+7. What can be gamed is said plainly in mode.json notes, with the cap that holds it.
+8. Randomness comes from drand through the beacon.
+9. The harness passes with the defaults and the edge of every setting, plus a test for every rule and action.
+10. Texts are short sentences, titles lower case, no dashes.
+
+## Submit
+
+`pickhooks-mode pack` writes one JSON file with your sources, tests, mode.json and the results. Send it on
+[pickhooks.com/modes/build](https://pickhooks.com/modes/build). No fee. When the mode passes, pickhooks deploys it,
+verifies it on BscScan, lists it, and the wallet in `mode.json` starts earning.
+
+MIT

package/bin/pickhooks-mode.mjs

@@ -0,0 +1,272 @@
+#!/usr/bin/env node
+// pickhooks-mode: write a mode for pickhooks coins, test it against the live contracts, pack it for review.
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { checkProject, sourceFiles } from "../lib/check.mjs";
+import { encodeSettings, encodeAction, validate } from "../lib/modejson.mjs";
+import { brief } from "../lib/brief.mjs";
+import { LIVE } from "../lib/live.mjs";
+
+const KIT = path.resolve(import.meta.dirname, "..");
+const VERSION = JSON.parse(fs.readFileSync(path.join(KIT, "package.json"), "utf8")).version;
+
+const HELP = `pickhooks-mode ${VERSION}: write a game for pickhooks coins (BNB Chain), test it, earn on every coin that uses it.
+
+  pickhooks-mode init <dir> [--contract MyMode] [--title "my mode"] [--name mymode] [--no-install]
+      a Foundry project with a whole working mode, its tests against the live contracts and its mode.json
+  pickhooks-mode check [dir] [--json]
+      mode.json, the source and the built bytecode against the rules every mode keeps
+  pickhooks-mode test [dir] [forge test args]
+      forge test on a BNB Chain fork (BSC_RPC_URL in .env): your mode on the live factory, the live coin code and
+      PancakeSwap's real routers
+  pickhooks-mode pack [dir] [--no-test]
+      check, test, and one file for the review: submission/<name>-<hash>.json
+  pickhooks-mode encode settings key=value ...          the settings as the factory takes them
+  pickhooks-mode encode action <name> key=value ...     a holder's play
+  pickhooks-mode encode poke <name> key=value ...       a poke
+  pickhooks-mode brief
+      the brief for a coding agent: paste it into Claude Code, Cursor or Codex with your idea
+  pickhooks-mode addresses
+      the live contracts a mode plugs into
+
+Submit: send the packed file to pickhooks (https://pickhooks.com/modes/build). No fee. pickhooks reviews it, deploys it
+and lists it; the author wallet in mode.json earns half of the pickhooks fee of every coin launched with the mode.`;
+
+function flags(argv) {
+  const pos = [];
+  const opt = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--") {
+      opt._rest = argv.slice(i + 1);
+      break;
+    }
+    if (a.startsWith("--")) {
+      const [k, v] = a.slice(2).split("=");
+      if (v !== undefined) opt[k] = v;
+      else if (argv[i + 1] !== undefined && !argv[i + 1].startsWith("--") && ["contract", "title", "name", "dir"].includes(k)) opt[k] = argv[++i];
+      else opt[k] = true;
+    } else pos.push(a);
+  }
+  return { pos, opt };
+}
+
+function die(msg, code = 1) {
+  console.error(msg);
+  process.exit(code);
+}
+
+function readEnv(dir) {
+  const env = {};
+  const f = path.join(dir, ".env");
+  if (!fs.existsSync(f)) return env;
+  for (const line of fs.readFileSync(f, "utf8").split(/\r?\n/)) {
+    const m = /^\s*([A-Z_][A-Z0-9_]*)\s*=\s*(.*?)\s*$/.exec(line);
+    if (m && m[2] !== "") env[m[1]] = m[2].replace(/^["']|["']$/g, "");
+  }
+  return env;
+}
+
+function copyDir(from, to, rename = (n) => n) {
+  fs.mkdirSync(to, { recursive: true });
+  for (const e of fs.readdirSync(from, { withFileTypes: true })) {
+    const src = path.join(from, e.name);
+    const dst = path.join(to, rename(e.name));
+    if (e.isDirectory()) copyDir(src, dst, rename);
+    else fs.copyFileSync(src, dst);
+  }
+}
+
+function forge() {
+  return process.env.FORGE || "forge";
+}
+
+function hasForge() {
+  const r = spawnSync(forge(), ["--version"], { encoding: "utf8", shell: process.platform === "win32" });
+  return r.status === 0;
+}
+
+// ------------------------------------------------------------------ init
+
+function init(pos, opt) {
+  const dir = path.resolve(pos[0] ?? "my-mode");
+  if (fs.existsSync(dir) && fs.readdirSync(dir).length) die(`${dir} is not empty`);
+  const contract = opt.contract ?? "HourMode";
+  if (!/^[A-Z][A-Za-z0-9_]*$/.test(contract)) die("--contract must be a Solidity contract name, like MyMode");
+  const title = opt.title ?? (contract === "HourMode" ? "first of the hour" : contract.replace(/Mode$/, "").replace(/([a-z])([A-Z])/g, "$1 $2").toLowerCase());
+  const name = opt.name ?? (title.replace(/[^a-z0-9]/g, "").replace(/^[0-9]+/, "").slice(0, 24) || "mymode");
+
+  const swap = (s) => s.replaceAll("HourMode", contract).replaceAll('"first of the hour"', JSON.stringify(title)).replaceAll("first of the hour:", `${title}:`);
+  copyDir(path.join(KIT, "template"), dir, (n) => (n === "gitignore" ? ".gitignore" : n === "env.example" ? ".env.example" : n.replace("HourMode", contract)));
+  for (const f of [path.join(dir, "src", `${contract}.sol`), path.join(dir, "test", `${contract}.t.sol`)]) fs.writeFileSync(f, swap(fs.readFileSync(f, "utf8")));
+  const mj = JSON.parse(fs.readFileSync(path.join(dir, "mode.json"), "utf8"));
+  Object.assign(mj, { name, title, contract });
+  fs.writeFileSync(path.join(dir, "mode.json"), JSON.stringify(mj, null, 2) + "\n");
+  copyDir(path.join(KIT, "contracts"), path.join(dir, "lib", "pickhooks"));
+  fs.copyFileSync(path.join(KIT, "schema", "mode.schema.json"), path.join(dir, "mode.schema.json"));
+
+  console.log(`${dir}\n  src/${contract}.sol      a whole mode (first of the hour), rename and rewrite it\n  test/${contract}.t.sol   its tests on a BNB Chain fork against the live factory\n  mode.json             what it is, in the launcher's words\n  lib/pickhooks/        the kit (do not edit)`);
+  if (opt["no-install"]) {
+    console.log(`\nforge-std: cd ${pos[0] ?? "my-mode"} && forge install foundry-rs/forge-std --no-git`);
+  } else if (hasForge()) {
+    const r = spawnSync(forge(), ["install", "foundry-rs/forge-std", "--no-git"], { cwd: dir, stdio: "inherit", shell: process.platform === "win32" });
+    if (r.status !== 0) console.log(`\nforge-std did not install; run it yourself: forge install foundry-rs/forge-std --no-git`);
+  } else {
+    console.log("\nFoundry is not installed: https://getfoundry.sh, then: forge install foundry-rs/forge-std --no-git");
+  }
+  console.log(`\nNext: put a BNB Chain RPC into .env (BSC_RPC_URL=...), then npx @pickhooks/mode-kit test`);
+}
+
+// ------------------------------------------------------------------ check
+
+function printCheck(r) {
+  for (const e of r.errors) console.log(`FAIL ${e}`);
+  for (const w of r.warnings) console.log(`WARN ${w}`);
+  if (r.facts.runtimeBytes) console.log(`OK   ${r.facts.runtimeBytes} bytes of runtime code (limit 24,576)`);
+  console.log(r.ok ? `OK   ${r.mode?.title ?? "the mode"}: no errors${r.warnings.length ? `, ${r.warnings.length} warnings for the review` : ""}` : `STOP ${r.errors.length} errors`);
+}
+
+function check(pos, opt) {
+  const dir = path.resolve(pos[0] ?? ".");
+  const r = checkProject(dir, { strict: !!opt.strict });
+  if (opt.json) console.log(JSON.stringify({ ok: r.ok, errors: r.errors, warnings: r.warnings, facts: r.facts }, null, 2));
+  else printCheck(r);
+  process.exitCode = r.ok ? 0 : 1;
+  return r;
+}
+
+// ------------------------------------------------------------------ test
+
+function runTests(dir, extra = [], quiet = false) {
+  if (!hasForge()) die("Foundry is not installed (https://getfoundry.sh). Set FORGE to its path if it is not on PATH.");
+  const env = { ...process.env, ...readEnv(dir) };
+  if (!env.FORK_RPC && !env.BSC_RPC_URL) die("Put a BNB Chain RPC into .env: BSC_RPC_URL=https://...");
+  env.FOUNDRY_PROFILE ??= "fork";
+  const r = spawnSync(forge(), ["test", ...extra], { cwd: dir, env, encoding: "utf8", shell: process.platform === "win32", maxBuffer: 64 << 20 });
+  const out = (r.stdout ?? "") + (r.stderr ?? "");
+  if (!quiet) process.stdout.write(out);
+  const m = /(\d+) tests passed, (\d+) failed, (\d+) skipped/.exec(out);
+  return { ok: r.status === 0, passed: m ? Number(m[1]) : null, failed: m ? Number(m[2]) : null, skipped: m ? Number(m[3]) : null, tail: out.split("\n").slice(-40).join("\n") };
+}
+
+function test(pos, opt) {
+  const dir = path.resolve(pos[0] ?? ".");
+  const r = runTests(dir, opt._rest ?? pos.slice(1));
+  process.exitCode = r.ok ? 0 : 1;
+}
+
+// ------------------------------------------------------------------ pack
+
+function pack(pos, opt) {
+  const dir = path.resolve(pos[0] ?? ".");
+  let t = null;
+  if (!opt["no-test"]) {
+    console.log("testing on a BNB Chain fork ...");
+    t = runTests(dir, [], true);
+    console.log(t.ok ? `OK   tests: ${t.passed} passed` : `FAIL tests:\n${t.tail}`);
+  }
+  const r = checkProject(dir, { strict: true });
+  printCheck(r);
+  if (!r.ok) die("Fix the errors above, then pack again.");
+  if (t && !t.ok) die("The tests fail. Fix them, then pack again.");
+
+  const files = {};
+  const add = (f) => (files[path.relative(dir, f).replace(/\\/g, "/")] = fs.readFileSync(f, "utf8"));
+  for (const f of sourceFiles(dir)) add(f);
+  for (const f of fs.existsSync(path.join(dir, "test")) ? fs.readdirSync(path.join(dir, "test"), { recursive: true }).map((x) => path.join(dir, "test", x)).filter((x) => x.endsWith(".sol")) : []) add(f);
+  for (const f of ["mode.json", "foundry.toml", "remappings.txt"]) if (fs.existsSync(path.join(dir, f))) add(path.join(dir, f));
+  const kitFiles = {};
+  for (const f of ["IStickyMode.sol", "ModeBase.sol"]) {
+    const p = path.join(dir, "lib", "pickhooks", f);
+    if (fs.existsSync(p)) kitFiles[f] = crypto.createHash("sha256").update(fs.readFileSync(p)).digest("hex");
+  }
+  const bundle = {
+    kind: "pickhooks mode submission",
+    kit: VERSION,
+    mode: r.mode,
+    check: { errors: r.errors, warnings: r.warnings, facts: r.facts },
+    test: t ? { ran: true, ok: t.ok, passed: t.passed, failed: t.failed } : { ran: false },
+    kitFiles,
+    files,
+  };
+  const body = JSON.stringify(bundle, null, 2);
+  const id = crypto.createHash("sha256").update(body).digest("hex").slice(0, 12);
+  fs.mkdirSync(path.join(dir, "submission"), { recursive: true });
+  const out = path.join(dir, "submission", `${r.mode.name}-${id}.json`);
+  fs.writeFileSync(out, body + "\n");
+  console.log(`\n${out}\nSend this file to pickhooks: https://pickhooks.com/modes/build (no fee). The author share goes to ${r.mode.author.wallet}.`);
+}
+
+// ------------------------------------------------------------------ encode
+
+function kv(list) {
+  const o = {};
+  for (const a of list) {
+    const i = a.indexOf("=");
+    if (i < 1) die(`expected key=value, got ${a}`);
+    o[a.slice(0, i)] = a.slice(i + 1);
+  }
+  return o;
+}
+
+function encodeCmd(pos, opt) {
+  const dir = path.resolve(opt.dir ?? ".");
+  const f = path.join(dir, "mode.json");
+  if (!fs.existsSync(f)) die(`no mode.json in ${dir}`);
+  const m = JSON.parse(fs.readFileSync(f, "utf8"));
+  const v = validate(m);
+  if (v.errors.length) die(`mode.json has errors, run pickhooks-mode check:\n${v.errors.join("\n")}`);
+  const [what, ...rest] = pos;
+  try {
+    if (what === "settings") console.log(encodeSettings(m, kv(rest)));
+    else if (what === "action" || what === "poke") {
+      const [name, ...args] = rest;
+      if (!name) die(`which ${what}? ${(m[what === "poke" ? "pokes" : "actions"] ?? []).map((a) => a.name).join(", ") || "(none)"}`);
+      console.log(encodeAction(m, name, kv(args), what === "poke" ? "pokes" : "actions"));
+    } else die("encode settings | action <name> | poke <name>");
+  } catch (e) {
+    die(e.message);
+  }
+}
+
+// ------------------------------------------------------------------ main
+
+const [cmd, ...argv] = process.argv.slice(2);
+const { pos, opt } = flags(argv);
+switch (cmd) {
+  case "init":
+    init(pos, opt);
+    break;
+  case "check":
+    check(pos, opt);
+    break;
+  case "test":
+    test(pos, opt);
+    break;
+  case "pack":
+    pack(pos, opt);
+    break;
+  case "encode":
+    encodeCmd(pos, opt);
+    break;
+  case "brief":
+    console.log(brief());
+    break;
+  case "addresses":
+    console.log(JSON.stringify(LIVE, null, 2));
+    break;
+  case undefined:
+  case "help":
+  case "--help":
+  case "-h":
+    console.log(HELP);
+    break;
+  case "--version":
+  case "-v":
+    console.log(VERSION);
+    break;
+  default:
+    die(`unknown command ${cmd}\n\n${HELP}`);
+}

package/contracts/IStickyMode.sol

@@ -0,0 +1,175 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.28;
+
+/// @title the mode of a sticky 3 coin
+/// @notice A sticky 3 coin carries one mode, fixed at launch. The coin calls it on every buy, sell and send, and passes
+///         on what holders and the keeper ask it to do (`play`, `poke`). A mode keeps its own state (a combo counter,
+///         a queue, a round) and answers with orders. It never moves a coin itself: the coin checks every
+///         order against its guardrails and carries it out (see StickyToken3 and Orders).
+///         One mode contract serves every coin that uses it; it tells the coins apart by the caller.
+interface IStickyMode {
+    /// @notice What the coin passes on every trade. `who` is the trader: the receiver of a buy or the sender of a sell
+    ///         or send, or the transaction's signer when that address is a contract (a router that forwards the coins).
+    struct Trade {
+        uint8 kind; // BUY 1, SELL 2, SEND 4
+        address from;
+        address to;
+        address who;
+        uint256 amount; // coins that left `from`
+        uint256 got; // coins that reached `to` (a buy: after the takes, with the rows' drop)
+        uint256 dev; // coins with the DEV mark that went into a pool or the pot in this trade
+        uint256 sniper; // the same for the SNIPER mark
+        uint256 pot; // the game pot after this trade's take
+        uint256 buys; // buys since launch, this one included
+    }
+
+    /// @notice The share of every buy (basis points) that goes into the game pot for these settings. Reverts when the
+    ///         settings are out of bounds. Called by the factory before the coin exists.
+    function quote(address creator, bytes calldata data) external view returns (uint16 gameBps);
+
+    /// @notice The factory registers a new coin with its settings, before the coin can trade.
+    function register(address coin, address creator, bytes calldata data) external;
+
+    /// @notice Called by the coin after every buy, sell and send, with a fixed gas budget. A mode that fails here only
+    ///         loses its effect on this trade: the trade goes through.
+    function onTrade(Trade calldata t) external returns (uint256[] memory orders);
+
+    /// @notice A holder's action, passed on by the coin (`coin.play(data)`). `player` is the caller of the coin.
+    function onPlay(address player, bytes calldata data) external returns (uint256[] memory orders);
+
+    /// @notice Anyone's nudge, passed on by the coin (`coin.poke(data)`): settle a round, open with drand, end a game.
+    function onPoke(address caller, bytes calldata data) external returns (uint256[] memory orders);
+
+    /// @notice The mode's name, as the launcher and the coin page show it.
+    function name() external view returns (string memory);
+}
+
+/// @notice What a mode reads of its coins.
+interface IStickyCoin3 {
+    function balanceOf(address) external view returns (uint256);
+    function totalSupply() external view returns (uint256);
+    function creator() external view returns (address);
+    function pool() external view returns (address);
+    function pool2() external view returns (address);
+    function start() external view returns (uint40);
+    function gamePot() external view returns (uint128);
+    function heldOf(address who) external view returns (uint256 amount, uint256 dev, uint40 until, uint40 since);
+    function aged(address who, uint256 before, uint8 skip) external view returns (uint256);
+    function play(bytes calldata data) external;
+    function poke(bytes calldata data) external;
+    function transfer(address to, uint256 amount) external returns (bool);
+    function transferFrom(address from, address to, uint256 amount) external returns (bool);
+    function approve(address spender, uint256 amount) external returns (bool);
+}
+
+/// @title the orders a mode can give
+/// @notice An order is three words: [kind | amount << 8 | until << 136 | flags << 176], [who], [to]. The coin reads a
+///         mode's answer as a plain uint256[] of such triples and carries out at most MAX orders. What each order may
+///         do is decided by the coin, not by the mode:
+///         - PAY: coins out of the game pot to `to`, as a fresh lot; into `to`'s custody until `until` when it is set.
+///           Never more than the pot. Coins paid to the creator carry the DEV mark.
+///         - HOLD: `amount` of `who`'s free coins into the custody of `to` (usually `who`) until `until`. Only in a
+///           play, and only the player's own coins. The coins leave by the send rules of the table. Flag NODEV: only
+///           coins without the DEV mark.
+///         - RELEASE: all of `who`'s custody back into `who`'s wallet, with the lots as they went in.
+///         - BURN_HELD: coins out of `who`'s custody to the dead address.
+///         - MOVE_HELD: coins out of `who`'s custody to `to`: into `to`'s wallet, or into `to`'s custody when `until`
+///           is set. The lots keep their time, marks and lock (like a send).
+///         - BURN_POT: coins out of the game pot to the dead address.
+///         - BURN: `amount` of `who`'s free coins to the dead address. Only in a play, only the player's own coins.
+///         - UNTIL: sets when `who`'s custody ends.
+///         Custody always ends by itself: the coin caps `until` at 7 days after the custody began (14 days for custody
+///         made in the launch block), and after `until` anyone can call `coin.releaseHeld(who)`.
+library Orders {
+    uint8 internal constant PAY = 1;
+    uint8 internal constant HOLD = 2;
+    uint8 internal constant RELEASE = 3;
+    uint8 internal constant BURN_HELD = 4;
+    uint8 internal constant MOVE_HELD = 5;
+    uint8 internal constant BURN_POT = 6;
+    uint8 internal constant BURN = 7;
+    uint8 internal constant UNTIL = 8;
+
+    /// HOLD: take only coins without the DEV mark
+    uint8 internal constant NODEV = 1;
+
+    uint256 internal constant MAX = 16;
+
+    struct List {
+        uint256[] w;
+        uint256 n; // words used
+    }
+
+    function list(uint256 orders) internal pure returns (List memory l) {
+        l.w = new uint256[](orders * 3);
+    }
+
+    function add(List memory l, uint8 kind, address who, address to, uint256 amount, uint256 until, uint8 flags)
+        internal
+        pure
+    {
+        if (l.n + 3 > l.w.length) {
+            // grow (a mode rarely needs more than it asked for)
+            uint256[] memory w = new uint256[](l.w.length * 2 + 3);
+            for (uint256 i; i < l.n; i++) {
+                w[i] = l.w[i];
+            }
+            l.w = w;
+        }
+        if (amount > type(uint128).max) amount = type(uint128).max;
+        if (until > type(uint40).max) until = type(uint40).max;
+        l.w[l.n] = uint256(kind) | (amount << 8) | (until << 136) | (uint256(flags) << 176);
+        l.w[l.n + 1] = uint256(uint160(who));
+        l.w[l.n + 2] = uint256(uint160(to));
+        l.n += 3;
+    }
+
+    function pay(List memory l, address to, uint256 amount) internal pure {
+        if (amount != 0) add(l, PAY, address(0), to, amount, 0, 0);
+    }
+
+    function payHeld(List memory l, address to, uint256 amount, uint256 until) internal pure {
+        if (amount != 0) add(l, PAY, address(0), to, amount, until, 0);
+    }
+
+    function hold(List memory l, address who, address to, uint256 amount, uint256 until, uint8 flags) internal pure {
+        add(l, HOLD, who, to, amount, until, flags);
+    }
+
+    function release(List memory l, address who) internal pure {
+        add(l, RELEASE, who, address(0), 0, 0, 0);
+    }
+
+    function burnHeld(List memory l, address who, uint256 amount) internal pure {
+        if (amount != 0) add(l, BURN_HELD, who, address(0), amount, 0, 0);
+    }
+
+    function moveHeld(List memory l, address who, address to, uint256 amount, uint256 until) internal pure {
+        if (amount != 0) add(l, MOVE_HELD, who, to, amount, until, 0);
+    }
+
+    function burnPot(List memory l, uint256 amount) internal pure {
+        if (amount != 0) add(l, BURN_POT, address(0), address(0), amount, 0, 0);
+    }
+
+    function burn(List memory l, address who, uint256 amount) internal pure {
+        add(l, BURN, who, address(0), amount, 0, 0);
+    }
+
+    function setUntil(List memory l, address who, uint256 t) internal pure {
+        add(l, UNTIL, who, address(0), 0, t, 0);
+    }
+
+    /// @notice The finished list: the words used, nothing behind them.
+    function done(List memory l) internal pure returns (uint256[] memory w) {
+        w = l.w;
+        uint256 n = l.n;
+        assembly ("memory-safe") {
+            mstore(w, n)
+        }
+    }
+
+    function none() internal pure returns (uint256[] memory) {
+        return new uint256[](0);
+    }
+}