@pickhooks/mode-kit 0.0.0-stage → 0.1.0

package/lib/brief.mjs

@@ -0,0 +1,122 @@
+// The brief for a coding agent (Claude Code, Cursor, Codex ...): everything it needs to write a mode, test it and
+// pack it, and what it must not do. `pickhooks-mode brief` prints it; paste it into the agent with your idea.
+import { LIVE } from "./live.mjs";
+
+export function brief() {
+  return `# Write a pickhooks mode
+
+You are writing a mode for pickhooks (pickhooks.com, BNB Chain): the game inside a coin. Every coin launched with
+the mode calls it after every buy, sell and send, and holders play it through the coin. You write one Solidity
+contract and its mode.json, test it on a BNB Chain fork against the live contracts, and pack it for review.
+pickhooks reviews it, deploys it and lists it. **Never deploy anything to mainnet yourself, never ask for a private
+key, never send a transaction.**
+
+## The project
+
+\`\`\`
+src/<Contract>.sol      the mode (start from src/HourMode.sol, a whole mode in one file)
+test/<Contract>.t.sol   its tests (start from test/HourMode.t.sol)
+mode.json               what it is, its settings and actions, in the words the launcher shows
+lib/pickhooks/          the kit: IStickyMode.sol, ModeBase.sol, harness/ (do not edit)
+\`\`\`
+
+Commands: \`npx @pickhooks/mode-kit check\` (mode.json, source, bytecode), \`npx @pickhooks/mode-kit test\` (forge on a
+fork, needs BSC_RPC_URL in .env), \`npx @pickhooks/mode-kit pack\` (the file for the review).
+
+## How a mode works
+
+Extend \`ModeBase\` and implement:
+
+- \`name()\`: the title, a plain string literal, the same as mode.json "title".
+- \`quote(creator, data)\`: decode the settings (\`abi.decode(data, (...))\`, empty data means defaults), check each
+  against its bounds with \`_within(x, default, lo, hi, "what")\` (0 means the default), revert outside them, and return
+  the share of every buy (basis points) that goes into the coin's game pot. The factory refuses a launch where this
+  share and the coin's own burns and pots pass 10 % of a buy.
+- \`_register(coin, creator, data)\`: store the settings per coin. State is always per coin: \`mapping(address => ...)\`.
+- \`_trade(coin, t)\`: called after every buy (kind 1), sell (2) and send (4). \`t.who\` is the trader (the coin
+  resolves routers and aggregators to their signer), \`t.amount\` the coins moved, \`t.got\` what a buyer got, \`t.pot\` the
+  pot after this trade, \`t.buys\` the buy counter. Return orders, or \`Orders.none()\`.
+- \`_play(coin, player, data)\`: a holder's move through \`coin.play(abi.encode(uint8 op, ...))\`. Optional.
+- \`_poke(coin, caller, data)\`: anyone's nudge through \`coin.poke(...)\`, to settle or end a round. Optional.
+
+Use the helpers of ModeBase: \`_player(coin, who)\` (false for the creator, the pools, the coin, the dead address),
+\`_ppm(coins)\` (millionths of the supply), \`_pot(coin)\`, \`_op(data)\`, \`_isWallet(a)\`, \`_min(a, b)\`.
+
+## Orders: the only way a mode acts
+
+A mode never moves a coin. It answers with orders built with \`Orders\` and the coin carries them out under its rules:
+
+| 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 until \`until\` |
+| 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.
+
+## What holds whatever the mode does
+
+- Every terminal trades the coin from the first second: GMGN, Binance Wallet, PancakeSwap, any router.
+- The mode gets 250,000 gas per trade. If it reverts, runs out of gas or answers garbage, the coin skips it for that
+  trade (\`ModeSkipped\`) and the trade stands. A mode that skips is broken: the harness fails on any skip and wants
+  every trade under 200,000 gas.
+- Sells and sends are never taxed. The pot fills only with the mode's share of buys and leaves only by orders.
+
+## Rules for the code (\`pickhooks-mode check\` enforces them)
+
+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 (use \`t.who\`). Randomness only from drand through the beacon at
+${LIVE.drandBeacon} (see the heist mode on BscScan for the pattern), never from block values. Every loop has a fixed
+bound. Constants are named, so the review can state them.
+
+## The review checklist
+
+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 (a full list, the last slot); 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 (_player), 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: two own wallets, a bot that times trades, a creator who plays
+   against holders, and the cap that holds it.
+8. Randomness comes from drand through the beacon.
+9. The harness passes: \`guardrails\` with the defaults and with the edge of every setting, \`stress\`, \`expectLaunchRevert\`
+   for every bound, and a test for every rule and action.
+10. Texts are short sentences, lower case titles, no dashes.
+
+## mode.json
+
+\`\`\`json
+{
+  "kit": 1,
+  "name": "hour",                      // the id: lower case letters and digits
+  "title": "first of the hour",        // = name() in the contract
+  "contract": "HourMode",
+  "line": "The first buy of every hour wins from the pot.",
+  "how": ["sentence", "sentence"],     // how it plays, 1 to 5 sentences
+  "share": "bps",                      // the setting that is the share of buys (or { "fixed": 200 })
+  "settings": [{ "key": "bps", "type": "uint256", "label": "...", "unit": "bps", "default": 200, "min": 100, "max": 300 }],
+  "actions": [{ "name": "try", "op": 1, "who": "holder", "text": "...", "params": [{ "key": "coins", "type": "uint256", "decimals": 18 }] }],
+  "pokes": [],
+  "drand": false, "custody": false, "keeper": null,
+  "notes": ["what can be gamed, and the cap that holds it"],
+  "author": { "wallet": "0x...", "x": "@...", "telegram": "@..." }
+}
+\`\`\`
+
+Settings are encoded in the order of the list (\`abi.encode\` of their types); an action's data is
+\`abi.encode(uint8 op, params...)\`. \`pickhooks-mode encode\` does both.
+
+## The author share
+
+When pickhooks lists the mode, the author wallet in mode.json earns half of the pickhooks fee of every coin launched
+with it, in BNB, for as long as those coins trade. The creator's share is not touched.
+`;
+}

package/lib/check.mjs

@@ -0,0 +1,158 @@
+// The checks pickhooks runs before it reviews a mode by hand: mode.json, the Solidity source and the built bytecode.
+// Errors stop a submission; warnings are what the reviewer will look at first.
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { validate } from "./modejson.mjs";
+
+/** BNB Chain refuses contracts over this many bytes of runtime code (EIP-170). */
+export const MAX_CODE = 24_576;
+
+/** Solidity without comments and string contents, so a word in a comment or a message never trips a check. */
+export function stripSolidity(src) {
+  return src
+    .replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, " "))
+    .replace(/\/\/[^\n]*/g, "")
+    .replace(/"(?:[^"\\\n]|\\.)*"/g, '""')
+    .replace(/'(?:[^'\\\n]|\\.)*'/g, "''");
+}
+
+/** What a mode's source may not contain, and why. */
+const FORBIDDEN = [
+  [/\bselfdestruct\s*\(/, "selfdestruct: a mode is there for every coin that uses it, for good"],
+  [/\bdelegatecall\b/, "delegatecall: the code that runs must be the code that was reviewed"],
+  [/\bcallcode\b/, "callcode: the code that runs must be the code that was reviewed"],
+  [/\btx\.origin\b/, "tx.origin: use the trade's `who` (the coin already resolves routers to their signer)"],
+  [/\bblock\.(prevrandao|difficulty)\b|\bblockhash\s*\(/, "block values as randomness: validators can steer them; draw with drand through the beacon"],
+  [/\bpayable\b|\breceive\s*\(\s*\)|\bfallback\s*\(/, "payable: a mode holds no BNB"],
+  [/\.call\s*[({]|\.staticcall\s*\(|\.send\s*\(/, "low level calls: a mode reads its coin and answers with orders, it calls nothing else"],
+  [/\.(transfer|transferFrom|approve)\s*\(/, "moving coins: a mode never moves a coin itself, it answers with orders the coin carries out"],
+  [/\.(play|poke|releaseHeld)\s*\(/, "calling back into the coin: the coin is busy while it asks the mode, the call would revert"],
+  [/\bnew\s+[A-Z]\w*\s*[({]/, "deploying contracts: a mode is one contract, reviewed as it is"],
+  [/\b(upgradeTo|upgradeToAndCall|_authorizeUpgrade|initialize|initializer)\b|\bProxy\b|\bUUPS\b/, "upgradeable: a mode is fixed, like the coins that use it"],
+  [/\b(Ownable|onlyOwner|transferOwnership|AccessControl)\b/, "an owner: nobody holds power over a listed mode, the coins keep it for good"],
+];
+
+/** What a reviewer will look at first. */
+const WATCH = [
+  [/\bassembly\b/, "assembly: the reviewer reads it line by line"],
+  [/\bwhile\s*\(/, "a while loop: make sure it ends in a fixed number of steps (250,000 gas per trade)"],
+  [/\bunchecked\b/, "unchecked math: say in a comment why it cannot overflow"],
+  [/\bblock\.number\b/, "block.number: BNB Chain blocks are 0.45 s and may change; prefer block.timestamp"],
+  [/\bI(?!StickyCoin3\b|StickyMode\b|Beacon\b)[A-Z]\w*\s*\(\s*\w+\s*\)\s*\./, "a call to another contract: say in mode.json notes which one and why"],
+];
+
+/** The runtime code without Solidity's CBOR metadata at the end. */
+export function stripMetadata(hex) {
+  const h = hex.replace(/^0x/, "");
+  if (h.length < 4) return h;
+  const len = parseInt(h.slice(-4), 16);
+  const cut = h.length - (len + 2) * 2;
+  return cut > 0 && len > 0 && len < 200 ? h.slice(0, cut) : h;
+}
+
+/** The opcodes in runtime code, walking past PUSH data so data bytes never count as opcodes. */
+export function opcodes(hex) {
+  const h = stripMetadata(hex);
+  const found = new Set();
+  for (let i = 0; i < h.length; i += 2) {
+    const op = parseInt(h.slice(i, i + 2), 16);
+    found.add(op);
+    if (op >= 0x60 && op <= 0x7f) i += (op - 0x5f) * 2;
+  }
+  return found;
+}
+
+const BAD_OPS = [
+  [0xff, "SELFDESTRUCT"],
+  [0xf4, "DELEGATECALL"],
+  [0xf2, "CALLCODE"],
+  [0xf0, "CREATE"],
+  [0xf5, "CREATE2"],
+];
+
+function walk(dir, ext, out = []) {
+  if (!fs.existsSync(dir)) return out;
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) walk(p, ext, out);
+    else if (p.endsWith(ext)) out.push(p);
+  }
+  return out;
+}
+
+export function sourceFiles(dir) {
+  return walk(path.join(dir, "src"), ".sol");
+}
+
+/** Checks a mode project: mode.json, every source file under src/, and the built bytecode when out/ has it. */
+export function checkProject(dir, { strict = false } = {}) {
+  const errors = [];
+  const warnings = [];
+  const facts = {};
+  const file = path.join(dir, "mode.json");
+  if (!fs.existsSync(file)) return { ok: false, errors: [`no mode.json in ${dir}`], warnings, facts };
+  let m;
+  try {
+    m = JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch (e) {
+    return { ok: false, errors: [`mode.json is not valid JSON: ${e.message}`], warnings, facts };
+  }
+  const v = validate(m, { strict });
+  errors.push(...v.errors.map((e) => `mode.json: ${e}`));
+  warnings.push(...v.warnings.map((e) => `mode.json: ${e}`));
+
+  const files = sourceFiles(dir);
+  if (!files.length) errors.push("src/ has no Solidity files");
+  let main = null;
+  const hash = crypto.createHash("sha256");
+  for (const f of files) {
+    const raw = fs.readFileSync(f, "utf8");
+    hash.update(path.relative(dir, f).replace(/\\/g, "/") + "\n" + raw);
+    const code = stripSolidity(raw);
+    const rel = path.relative(dir, f).replace(/\\/g, "/");
+    for (const [re, why] of FORBIDDEN) if (re.test(code)) errors.push(`${rel}: ${why}`);
+    for (const [re, why] of WATCH) if (re.test(code)) warnings.push(`${rel}: ${why}`);
+    for (const imp of raw.matchAll(/^\s*import\s+[^;]*?["']([^"']+)["']/gm)) {
+      const p = imp[1];
+      if (!p.startsWith("pickhooks/") && !p.startsWith("./") && !p.startsWith("../")) warnings.push(`${rel}: imports ${p}; the review reads every imported line, keep it to the kit and your own files`);
+      if (p.startsWith("pickhooks/harness/")) errors.push(`${rel}: the harness is for tests, not for the mode`);
+    }
+    if (m?.contract && new RegExp(`\\bcontract\\s+${m.contract}\\b`).test(code)) main = { rel, raw, code };
+  }
+  facts.sourceSha256 = hash.digest("hex");
+
+  if (m?.contract && !main) errors.push(`no contract ${m.contract} under src/ (mode.json says contract "${m.contract}")`);
+  if (main) {
+    if (!new RegExp(`\\bcontract\\s+${m.contract}\\s+is\\s+[^{]*\\bModeBase\\b`).test(main.code)) errors.push(`${main.rel}: ${m.contract} must extend ModeBase (registration by the factory only, the coin check on every call)`);
+    if (!/\bModeBase\s*\(/.test(main.code)) errors.push(`${main.rel}: the constructor must pass the factory to ModeBase(factory_)`);
+    const nm = /function\s+name\s*\(\s*\)[^{]*\{\s*return\s+"([^"]*)"\s*;/.exec(main.raw);
+    if (!nm) errors.push(`${main.rel}: name() must return the title as a plain string literal`);
+    else if (m.title && nm[1] !== m.title) errors.push(`${main.rel}: name() returns "${nm[1]}", mode.json says "${m.title}"`);
+    if (!/function\s+quote\s*\(/.test(main.code)) errors.push(`${main.rel}: quote() is missing (the share of buys, and the bounds of the settings)`);
+    if (m?.drand && !/\bIBeacon\b|\bbeacon\b/.test(main.code)) warnings.push(`${main.rel}: mode.json says drand, the source does not use the beacon`);
+    if ((m?.actions ?? []).length && !/function\s+_play\s*\(/.test(main.code)) errors.push(`${main.rel}: mode.json has actions, the contract has no _play`);
+    if ((m?.pokes ?? []).length && !/function\s+_poke\s*\(/.test(main.code)) errors.push(`${main.rel}: mode.json has pokes, the contract has no _poke`);
+  }
+
+  // the built code, when forge built it
+  if (m?.contract && main) {
+    const art = path.join(dir, "out", path.basename(main.rel), `${m.contract}.json`);
+    if (fs.existsSync(art)) {
+      const j = JSON.parse(fs.readFileSync(art, "utf8"));
+      const hex = j.deployedBytecode?.object ?? "";
+      const size = hex.replace(/^0x/, "").length / 2;
+      facts.runtimeBytes = size;
+      facts.runtimeSha256 = crypto.createHash("sha256").update(hex.replace(/^0x/, ""), "hex").digest("hex");
+      if (size > MAX_CODE) errors.push(`the runtime code is ${size} bytes; BNB Chain takes at most ${MAX_CODE}`);
+      else if (size > 22_000) warnings.push(`the runtime code is ${size} bytes, close to the limit of ${MAX_CODE}`);
+      const ops = opcodes(hex);
+      for (const [op, n] of BAD_OPS) if (ops.has(op)) errors.push(`the bytecode contains ${n}`);
+      facts.compiler = j.metadata?.compiler?.version ?? null;
+      facts.evm = j.metadata?.settings?.evmVersion ?? null;
+    } else {
+      warnings.push(`no build in out/ yet: run forge build (or pickhooks-mode test) to check the bytecode too`);
+    }
+  }
+  return { ok: errors.length === 0, errors, warnings, facts, mode: m };
+}

package/lib/index.mjs

@@ -0,0 +1,6 @@
+// @pickhooks/mode-kit as a library: check a mode project, validate and encode mode.json, the live addresses, the brief.
+export { checkProject, stripSolidity, opcodes, stripMetadata, MAX_CODE } from "./check.mjs";
+export { validate, encodeSettings, encodeAction, shareBps, MAX_SHARE_BPS } from "./modejson.mjs";
+export { encode } from "./abi.mjs";
+export { LIVE } from "./live.mjs";
+export { brief } from "./brief.mjs";

package/lib/live.mjs

@@ -0,0 +1,14 @@
+// The live pickhooks contracts a mode plugs into (BNB Chain, chain id 56). The same addresses as contracts/harness/Live.sol.
+export const LIVE = {
+  chainId: 56,
+  factory: "0x4b41a3Ee8C80C568aE6Da7C5572867D5640C0574",
+  locker: "0xCea0C138612B3F61D472d18F575Bb314561c024F",
+  drandBeacon: "0x9c264D2934B2027Bad622417b6747E558EC465CC",
+  wbnb: "0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c",
+  routerV3: "0x1b81D678ffb9C0263b24A97847620C99d213eB14",
+  routerV2: "0x10ED43C718714eb63d5aA57B78B54704E256024E",
+  modeGas: 250_000,
+  maxOrders: 16,
+  maxCustodyDays: 7,
+  maxShareBps: 1000,
+};

package/lib/modejson.mjs

@@ -0,0 +1,176 @@
+// mode.json: what a mode is, in the words and numbers the launcher, the coin page, the SDK and the review use.
+// validate() checks it, encodeSettings() / encodeAction() turn values into the bytes the chain takes.
+import { encode, isStatic, isType, toBig } from "./abi.mjs";
+
+/** The share of a buy all takes of a coin together (burns, pots and the mode) may not pass: the factory's validator. */
+export const MAX_SHARE_BPS = 1000;
+const WHO = ["holder", "creator", "anyone", "keeper"];
+const DASH = /[‒–—―]| - /;
+
+function texts(m) {
+  const out = [];
+  const add = (where, s) => typeof s === "string" && out.push([where, s]);
+  add("title", m.title);
+  add("line", m.line);
+  (m.how ?? []).forEach((s, i) => add(`how[${i}]`, s));
+  (m.notes ?? []).forEach((s, i) => add(`notes[${i}]`, s));
+  (m.settings ?? []).forEach((s, i) => add(`settings[${i}].label`, s?.label));
+  for (const list of ["actions", "pokes"]) (m[list] ?? []).forEach((a, i) => add(`${list}[${i}].text`, a?.text));
+  add("keeper", m.keeper);
+  return out;
+}
+
+function checkParams(where, params, errors) {
+  if (params === undefined) return;
+  if (!Array.isArray(params)) return errors.push(`${where}.params must be a list`);
+  const keys = new Set();
+  params.forEach((p, i) => {
+    const w = `${where}.params[${i}]`;
+    if (!p || typeof p !== "object") return errors.push(`${w} must be an object`);
+    if (!/^[a-z][A-Za-z0-9]*$/.test(p.key ?? "")) errors.push(`${w}.key must be a camelCase word`);
+    if (keys.has(p.key)) errors.push(`${w}.key "${p.key}" is used twice`);
+    keys.add(p.key);
+    if (!isType(p.type ?? "")) errors.push(`${w}.type "${p.type}" is not an ABI type the kit encodes`);
+    if (p.decimals !== undefined && !(Number.isInteger(p.decimals) && p.decimals >= 0 && p.decimals <= 36)) errors.push(`${w}.decimals must be 0 to 36`);
+  });
+}
+
+/**
+ * Checks a mode.json. `strict` (for a submission) also wants the author's wallet. Returns { errors, warnings }:
+ * errors stop a submission, warnings are what a reviewer will ask about.
+ */
+export function validate(m, { strict = false } = {}) {
+  const errors = [];
+  const warnings = [];
+  if (!m || typeof m !== "object") return { errors: ["mode.json is not an object"], warnings };
+  if (m.kit !== 1) errors.push(`kit must be 1 (this kit's format), got ${JSON.stringify(m.kit)}`);
+  if (!/^[a-z][a-z0-9]{1,23}$/.test(m.name ?? "")) errors.push("name must be 2 to 24 lower case letters and digits (it becomes the mode's id)");
+  if (typeof m.title !== "string" || m.title.length < 2 || m.title.length > 32) errors.push("title must be 2 to 32 characters (it must equal the contract's name())");
+  else if (m.title !== m.title.toLowerCase()) warnings.push("title: mode names are lower case on pickhooks (\"pay it forward\", \"heist\")");
+  if (!/^[A-Z][A-Za-z0-9_]*$/.test(m.contract ?? "")) errors.push("contract must be the Solidity contract's name");
+  if (typeof m.line !== "string" || m.line.length < 8 || m.line.length > 80) errors.push("line must be 8 to 80 characters: the mode in one sentence");
+  if (!Array.isArray(m.how) || m.how.length < 1 || m.how.length > 5) errors.push("how must be 1 to 5 sentences: how it plays");
+  else m.how.forEach((s, i) => (typeof s !== "string" || s.length > 220) && errors.push(`how[${i}] must be a sentence of at most 220 characters`));
+  if (!Array.isArray(m.notes) || m.notes.length < 1) errors.push("notes must say plainly what can be gamed and which cap holds it (at least one)");
+
+  // settings
+  const settings = m.settings ?? [];
+  if (!Array.isArray(settings) || settings.length > 8) errors.push("settings must be a list of at most 8");
+  const keys = new Set();
+  (Array.isArray(settings) ? settings : []).forEach((s, i) => {
+    const w = `settings[${i}]`;
+    if (!s || typeof s !== "object") return errors.push(`${w} must be an object`);
+    if (!/^[a-z][A-Za-z0-9]*$/.test(s.key ?? "")) errors.push(`${w}.key must be a camelCase word`);
+    if (keys.has(s.key)) errors.push(`${w}.key "${s.key}" is used twice`);
+    keys.add(s.key);
+    if (!isStatic(s.type ?? "")) return errors.push(`${w}.type must be a static ABI type (uint256, bool, address ...)`);
+    if (typeof s.label !== "string" || !s.label) errors.push(`${w}.label is missing`);
+    if (/int/.test(s.type)) {
+      try {
+        const [d, lo, hi] = [toBig(s.default), toBig(s.min), toBig(s.max)];
+        if (!(lo <= d && d <= hi)) errors.push(`${w}: min <= default <= max does not hold`);
+      } catch {
+        errors.push(`${w}: default, min and max must be numbers`);
+      }
+    }
+  });
+
+  // the share of buys
+  if (typeof m.share === "string") {
+    const s = (Array.isArray(settings) ? settings : []).find((x) => x?.key === m.share);
+    if (!s) errors.push(`share names the setting "${m.share}", which is not in settings`);
+    else if (!/^uint/.test(s.type)) errors.push(`share: the setting "${m.share}" must be a uint`);
+    else if (Number(s.max) > MAX_SHARE_BPS) errors.push(`share: at most ${MAX_SHARE_BPS} bps (10 % of a buy, burns and pots of the coin included)`);
+    else if (Number(s.max) > 500) warnings.push("share: over 5 % of every buy is a lot; scanners show buy takes, and it leaves less room for the coin's rows");
+  } else if (m.share && typeof m.share === "object" && Number.isInteger(m.share.fixed)) {
+    if (m.share.fixed < 0 || m.share.fixed > MAX_SHARE_BPS) errors.push(`share.fixed must be 0 to ${MAX_SHARE_BPS} bps`);
+  } else errors.push('share must name the setting that is the share of every buy into the pot, or be { "fixed": bps }');
+
+  // plays and pokes
+  for (const list of ["actions", "pokes"]) {
+    const xs = m[list] ?? [];
+    if (!Array.isArray(xs)) {
+      errors.push(`${list} must be a list`);
+      continue;
+    }
+    const ops = new Set();
+    xs.forEach((a, i) => {
+      const w = `${list}[${i}]`;
+      if (!a || typeof a !== "object") return errors.push(`${w} must be an object`);
+      if (!/^[a-z][a-z0-9 ]{0,23}$/.test(a.name ?? "")) errors.push(`${w}.name must be 1 to 24 lower case letters, digits and spaces`);
+      if (!(Number.isInteger(a.op) && a.op >= 0 && a.op <= 255)) errors.push(`${w}.op must be the action number 0 to 255 (the first word of the data)`);
+      if (ops.has(a.op)) errors.push(`${w}.op ${a.op} is used twice`);
+      ops.add(a.op);
+      if (!WHO.includes(a.who)) errors.push(`${w}.who must be one of ${WHO.join(", ")}`);
+      if (typeof a.text !== "string" || !a.text) errors.push(`${w}.text is missing`);
+      checkParams(w, a.params, errors);
+    });
+  }
+
+  if (typeof m.drand !== "boolean") errors.push("drand must be true or false (does the mode wait for drand rounds?)");
+  if (typeof m.custody !== "boolean") errors.push("custody must be true or false (can coins sit in custody?)");
+  if (!(m.keeper === null || typeof m.keeper === "string")) errors.push("keeper must be null or what the keeper does");
+  if ((m.drand || (m.pokes ?? []).length) && !m.keeper) warnings.push("keeper: a mode with drand or pokes needs someone to move it on; say what the keeper does");
+
+  // the author
+  const wallet = m.author?.wallet ?? "";
+  if (!/^0x[0-9a-fA-F]{40}$/.test(wallet)) (strict ? errors : warnings).push("author.wallet: the BNB Chain wallet the author share is paid to");
+
+  // house style
+  for (const [where, s] of texts(m)) if (DASH.test(s)) errors.push(`${where}: no dashes in texts, write two sentences or use a colon`);
+
+  if (m.address !== undefined && m.address !== null && !/^0x[0-9a-fA-F]{40}$/.test(m.address)) errors.push("address must be empty until pickhooks deploys the mode");
+  return { errors, warnings };
+}
+
+function valueOf(p, raw) {
+  if (raw === undefined) return undefined;
+  if (/int/.test(p.type) && !p.type.endsWith("[]")) return toBig(raw, p.decimals ?? 0);
+  return raw;
+}
+
+/**
+ * The settings as the factory takes them (`modeData`). `values` maps keys to values; a missing key takes its default.
+ * Nothing at all gives "0x": the mode's own defaults.
+ */
+export function encodeSettings(m, values = {}) {
+  const settings = m.settings ?? [];
+  for (const k of Object.keys(values)) if (!settings.some((s) => s.key === k)) throw new Error(`${m.title} has no setting "${k}"`);
+  if (!Object.keys(values).length) return "0x";
+  const out = settings.map((s) => {
+    const v = values[s.key] !== undefined ? valueOf(s, values[s.key]) : s.default;
+    if (/int/.test(s.type)) {
+      const n = toBig(v);
+      if (n < toBig(s.min) || n > toBig(s.max)) throw new Error(`${m.title}: ${s.key} is ${s.min} to ${s.max}`);
+      return n;
+    }
+    return v;
+  });
+  return encode(
+    settings.map((s) => s.type),
+    out,
+  );
+}
+
+/** A play's (or a poke's) data: abi.encode(uint8 op, params...). */
+export function encodeAction(m, name, values = {}, list = "actions") {
+  const a = (m[list] ?? []).find((x) => x.name === name);
+  if (!a) throw new Error(`${m.title} has no ${list === "pokes" ? "poke" : "action"} "${name}"`);
+  const params = a.params ?? [];
+  for (const k of Object.keys(values)) if (!params.some((p) => p.key === k)) throw new Error(`"${name}" has no parameter "${k}"`);
+  const vals = params.map((p) => {
+    if (values[p.key] === undefined) throw new Error(`"${name}" needs ${p.key}`);
+    return valueOf(p, values[p.key]);
+  });
+  return encode(
+    ["uint8", ...params.map((p) => p.type)],
+    [a.op, ...vals],
+  );
+}
+
+/** The share of every buy this mode takes with these settings (offline; the mode's quote() is the truth). */
+export function shareBps(m, values = {}) {
+  if (m.share && typeof m.share === "object") return m.share.fixed;
+  const s = (m.settings ?? []).find((x) => x.key === m.share);
+  return Number(values[m.share] ?? s?.default ?? 0);
+}

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@pickhooks/mode-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Write a game for pickhooks coins on BNB Chain, test it on a fork against the live contracts, earn half of the pickhooks fee of every coin that uses it.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "pickhooks-mode": "bin/pickhooks-mode.mjs"
+  },
+  "exports": {
+    ".": "./lib/index.mjs",
+    "./mode.schema.json": "./schema/mode.schema.json"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "contracts",
+    "template",
+    "schema",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/kit.test.mjs",
+    "sync": "node scripts/sync-check.mjs",
+    "release": "node scripts/publish.mjs"
+  },
+  "keywords": [
+    "pickhooks",
+    "bnb-chain",
+    "pancakeswap",
+    "foundry",
+    "solidity",
+    "hooks",
+    "launchpad",
+    "memecoin"
+  ],
+  "engines": {
+    "node": ">=20"
+  }
+}

package/schema/mode.schema.json

@@ -0,0 +1,80 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://pickhooks.com/schema/mode.schema.json",
+  "title": "pickhooks mode",
+  "description": "What a pickhooks mode is, in the words the launcher and the coin page show. `pickhooks-mode check` checks more than this schema.",
+  "type": "object",
+  "required": ["kit", "name", "title", "contract", "line", "how", "share", "settings", "actions", "drand", "custody", "keeper", "notes", "author"],
+  "properties": {
+    "kit": { "const": 1 },
+    "name": { "type": "string", "pattern": "^[a-z][a-z0-9]{1,23}$", "description": "the id: lower case letters and digits" },
+    "title": { "type": "string", "minLength": 2, "maxLength": 32, "description": "the name players see; equals name() in the contract" },
+    "contract": { "type": "string", "pattern": "^[A-Z][A-Za-z0-9_]*$" },
+    "line": { "type": "string", "minLength": 8, "maxLength": 80, "description": "the mode in one sentence" },
+    "how": { "type": "array", "minItems": 1, "maxItems": 5, "items": { "type": "string", "maxLength": 220 } },
+    "share": {
+      "description": "the setting that is the share of every buy into the game pot (basis points), or a fixed share",
+      "oneOf": [{ "type": "string" }, { "type": "object", "required": ["fixed"], "properties": { "fixed": { "type": "integer", "minimum": 0, "maximum": 1000 } } }]
+    },
+    "settings": {
+      "type": "array",
+      "maxItems": 8,
+      "items": {
+        "type": "object",
+        "required": ["key", "type", "label"],
+        "properties": {
+          "key": { "type": "string", "pattern": "^[a-z][A-Za-z0-9]*$" },
+          "type": { "type": "string", "description": "a static ABI type: uint256, int256, bool, address, bytes32 ..." },
+          "label": { "type": "string" },
+          "unit": { "type": "string", "description": "bps, ppm, seconds, coins, wallets ..." },
+          "default": {},
+          "min": {},
+          "max": {}
+        }
+      }
+    },
+    "actions": { "$ref": "#/$defs/actions" },
+    "pokes": { "$ref": "#/$defs/actions" },
+    "drand": { "type": "boolean" },
+    "custody": { "type": "boolean" },
+    "keeper": { "type": ["string", "null"] },
+    "notes": { "type": "array", "minItems": 1, "items": { "type": "string" }, "description": "said plainly: what can be gamed, and the cap that holds it" },
+    "author": {
+      "type": "object",
+      "properties": {
+        "wallet": { "type": "string", "description": "the BNB Chain wallet the author share is paid to" },
+        "x": { "type": "string" },
+        "telegram": { "type": "string" }
+      }
+    },
+    "address": { "type": ["string", "null"], "description": "set by pickhooks after the deploy" }
+  },
+  "$defs": {
+    "actions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "op", "who", "text"],
+        "properties": {
+          "name": { "type": "string", "pattern": "^[a-z][a-z0-9 ]{0,23}$" },
+          "op": { "type": "integer", "minimum": 0, "maximum": 255, "description": "the first word of the data: abi.encode(uint8 op, ...)" },
+          "who": { "enum": ["holder", "creator", "anyone", "keeper"] },
+          "text": { "type": "string" },
+          "params": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["key", "type"],
+              "properties": {
+                "key": { "type": "string" },
+                "type": { "type": "string" },
+                "label": { "type": "string" },
+                "decimals": { "type": "integer", "minimum": 0, "maximum": 36, "description": "18 for coins: 1.5 becomes 1.5e18" }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/template/env.example

@@ -0,0 +1,2 @@
+# a BNB Chain RPC with archive or recent state (NodeReal, QuickNode, Alchemy ...). The harness forks it.
+BSC_RPC_URL=

package/template/foundry.toml

@@ -0,0 +1,15 @@
+[profile.default]
+src = "src"
+test = "test"
+out = "out"
+libs = ["lib"]
+solc = "0.8.28"
+optimizer = true
+optimizer_runs = 200
+via_ir = true
+# the bytecode is built for cancun, as on BNB Chain mainnet
+evm_version = "cancun"
+
+# `pickhooks-mode test` runs this profile: prague has the BLS12-381 precompiles the drand beacon checks signatures with
+[profile.fork]
+evm_version = "prague"

package/template/gitignore

@@ -0,0 +1,5 @@
+out/
+cache/
+.env
+lib/forge-std/
+submission/