@pickhooks/mode-kit 0.0.0-stage → 0.1.0

package/contracts/ModeBase.sol

@@ -0,0 +1,124 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.28;
+
+import {IStickyMode, IStickyCoin3, Orders} from "./IStickyMode.sol";
+
+/// @title the base of every pickhooks mode
+/// @notice Registration by the factory, the coin check on every call, and the helpers all modes share. A mode keeps
+///         its state per coin (the caller) and answers with orders; it holds no coins and no BNB.
+abstract contract ModeBase is IStickyMode {
+    error NotFactory();
+    error NotCoin();
+    error Bad(string what);
+
+    uint256 internal constant SUPPLY = 1_000_000_000 ether;
+    uint8 internal constant BUY = 1;
+    uint8 internal constant SELL = 2;
+    uint8 internal constant SEND = 4;
+    address internal constant DEAD = 0x000000000000000000000000000000000000dEaD;
+
+    /// @notice The only factory that registers coins with this mode.
+    address public immutable factory;
+    /// @notice The creator of each coin of this mode (0: not a coin of this mode).
+    mapping(address => address) public creatorOf;
+
+    event Registered(address indexed coin, address indexed creator, bytes data);
+
+    constructor(address factory_) {
+        factory = factory_;
+    }
+
+    modifier onlyCoin() {
+        if (creatorOf[msg.sender] == address(0)) revert NotCoin();
+        _;
+    }
+
+    function register(address coin, address creator, bytes calldata data) external {
+        if (msg.sender != factory) revert NotFactory();
+        if (creatorOf[coin] != address(0) || creator == address(0)) revert Bad("registered");
+        creatorOf[coin] = creator;
+        _register(coin, creator, data);
+        emit Registered(coin, creator, data);
+    }
+
+    function onTrade(Trade calldata t) external onlyCoin returns (uint256[] memory) {
+        return _trade(msg.sender, t);
+    }
+
+    function onPlay(address player, bytes calldata data) external onlyCoin returns (uint256[] memory) {
+        return _play(msg.sender, player, data);
+    }
+
+    function onPoke(address caller, bytes calldata data) external onlyCoin returns (uint256[] memory) {
+        return _poke(msg.sender, caller, data);
+    }
+
+    function _register(address coin, address creator, bytes calldata data) internal virtual;
+
+    function _trade(address, Trade calldata) internal virtual returns (uint256[] memory) {
+        return Orders.none();
+    }
+
+    function _play(address, address, bytes calldata) internal virtual returns (uint256[] memory) {
+        revert Bad("no play");
+    }
+
+    function _poke(address, address, bytes calldata) internal virtual returns (uint256[] memory) {
+        revert Bad("no poke");
+    }
+
+    // ---------------------------------------------------------------- helpers
+
+    /// @dev Millionths of the supply.
+    function _ppm(uint256 amount) internal pure returns (uint256) {
+        return amount * 1e6 / SUPPLY;
+    }
+
+    function _coinsOfPpm(uint256 ppm) internal pure returns (uint256) {
+        return SUPPLY * ppm / 1e6;
+    }
+
+    /// @dev A holder a game may reward: not the creator, not a pool, not the coin, not the dead address.
+    function _player(address coin, address who) internal view returns (bool) {
+        if (who == address(0) || who == DEAD || who == coin || who == creatorOf[coin]) return false;
+        IStickyCoin3 c = IStickyCoin3(coin);
+        return who != c.pool() && who != c.pool2();
+    }
+
+    function _pot(address coin) internal view returns (uint256) {
+        return IStickyCoin3(coin).gamePot();
+    }
+
+    function _min(uint256 a, uint256 b) internal pure returns (uint256) {
+        return a < b ? a : b;
+    }
+
+    /// @dev The action of play or poke data: its first word (`abi.encode(uint8 action, ...)`).
+    function _op(bytes calldata data) internal pure returns (uint8) {
+        if (data.length < 32) revert Bad("no action");
+        return abi.decode(data[:32], (uint8));
+    }
+
+    /// @dev A wallet: no code, or an EIP-7702 delegation.
+    function _isWallet(address a) internal view returns (bool) {
+        uint256 size;
+        assembly ("memory-safe") {
+            size := extcodesize(a)
+        }
+        if (size == 0) return true;
+        if (size != 23) return false;
+        bytes32 h;
+        assembly ("memory-safe") {
+            extcodecopy(a, 0, 0, 3)
+            h := mload(0)
+        }
+        return bytes3(h) == 0xef0100;
+    }
+
+    /// @dev Settings in a range: `x` when set, the default `d` when zero; reverts outside [lo, hi].
+    function _within(uint256 x, uint256 d, uint256 lo, uint256 hi, string memory what) internal pure returns (uint256) {
+        if (x == 0) x = d;
+        if (x < lo || x > hi) revert Bad(what);
+        return x;
+    }
+}

package/contracts/harness/Live.sol

@@ -0,0 +1,80 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.28;
+
+import {IStickyCoin3} from "../IStickyMode.sol";
+
+/// @title the live pickhooks contracts a mode plugs into (BNB Chain, chain id 56)
+/// @notice The harness forks BNB Chain and runs a mode against these exact contracts: the sticky 3 factory that is live
+///         on pickhooks.com, the coin code it deploys, and PancakeSwap's real routers and pools.
+library Live {
+    /// @notice The sticky 3 factory (verified on BscScan). Only its owner lists a mode (`setMode`).
+    address internal constant FACTORY = 0x4b41a3Ee8C80C568aE6Da7C5572867D5640C0574;
+    /// @notice The drand quicknet beacon modes that draw use (verified on BscScan).
+    address internal constant DRAND_BEACON = 0x9c264D2934B2027Bad622417b6747E558EC465CC;
+    /// @notice The fee locker of the sticky 3 factory: collects each coin's fees (creator side, platform side).
+    address internal constant LOCKER = 0xCea0C138612B3F61D472d18F575Bb314561c024F;
+    address internal constant WBNB = 0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c;
+    /// @notice PancakeSwap V3 SwapRouter (the coin's curve is a 1 % V3 pool).
+    address internal constant ROUTER_V3 = 0x1b81D678ffb9C0263b24A97847620C99d213eB14;
+    /// @notice PancakeSwap V2 router (every coin also has a V2 pair, LP burned).
+    address internal constant ROUTER_V2 = 0x10ED43C718714eb63d5aA57B78B54704E256024E;
+}
+
+/// @notice The live factory, as far as a mode and its tests need it.
+interface IStickyFactory3 {
+    struct LaunchArgs {
+        string name;
+        string symbol;
+        string metadata;
+        uint256[] rows;
+        uint32 release;
+        bytes32 salt;
+        uint16 keepBps;
+        uint16 minCreatorBps;
+        address switcher;
+        uint8 switchMask;
+        address mode;
+        bytes modeData;
+    }
+
+    event ModeLaunched(address indexed token, address indexed mode, uint16 gameBps, bytes data);
+
+    function launch(LaunchArgs calldata a) external payable returns (address token);
+    function setMode(address m, bool on) external;
+    function modes(address m) external view returns (bool);
+    function owner() external view returns (address);
+    function seedBnb() external view returns (uint256);
+}
+
+/// @notice The live coin, as far as a mode's tests need it (the mode itself reads `IStickyCoin3`).
+interface IStickyCoin3Live is IStickyCoin3 {
+    event ModeSkipped(uint8 kind);
+
+    function MODE_GAS() external view returns (uint256);
+    function mode() external view returns (address);
+    function shadow(address who) external pure returns (address);
+    function releaseHeld(address who) external;
+}
+
+interface ISwapRouterV3 {
+    struct ExactInputSingleParams {
+        address tokenIn;
+        address tokenOut;
+        uint24 fee;
+        address recipient;
+        uint256 deadline;
+        uint256 amountIn;
+        uint256 amountOutMinimum;
+        uint160 sqrtPriceLimitX96;
+    }
+
+    function exactInputSingle(ExactInputSingleParams calldata params) external payable returns (uint256 amountOut);
+}
+
+interface IRouterV2 {
+    function swapExactETHForTokensSupportingFeeOnTransferTokens(uint256, address[] calldata, address, uint256)
+        external
+        payable;
+    function swapExactTokensForETHSupportingFeeOnTransferTokens(uint256, uint256, address[] calldata, address, uint256)
+        external;
+}

package/contracts/harness/ModeHarness.sol

@@ -0,0 +1,322 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.28;
+
+import {Test, Vm} from "forge-std/Test.sol";
+import {IStickyMode} from "../IStickyMode.sol";
+import {Live, IStickyFactory3, IStickyCoin3Live, ISwapRouterV3, IRouterV2} from "./Live.sol";
+
+/// @title the mode kit's harness
+/// @notice Forks BNB Chain, lists your mode on the live sticky 3 factory (as its owner, on the fork only), launches
+///         coins with it and trades them the way every terminal does: the V3 router, the V2 router, plain sends. The
+///         coin code, the pools and the routers are the live ones, so what passes here is what runs on pickhooks.com.
+///
+///         Extend it, return your mode from `deployMode`, and call `guardrails` and `stress` with your settings. Then
+///         write your own tests for every rule, action and bound of your mode with the helpers below.
+abstract contract ModeHarness is Test {
+    uint256 internal constant SUPPLY = 1_000_000_000 ether;
+    uint8 internal constant BUY = 1;
+    uint8 internal constant SELL = 2;
+    uint8 internal constant SEND = 4;
+    /// @notice The gas a mode may use for one trade in the harness: 80 % of the coin's budget (`MODE_GAS`, 250,000),
+    ///         so the mode keeps headroom. Over the budget the coin skips the mode for that trade.
+    uint256 internal constant MODE_GAS_LIMIT = 200_000;
+    bytes32 internal constant MODE_SKIPPED = keccak256("ModeSkipped(uint8)");
+
+    IStickyFactory3 internal factory;
+    /// @notice Your mode, listed on the fork.
+    address internal mode;
+    /// @notice The coin of the last launch.
+    IStickyCoin3Live internal coin;
+    /// @notice The coin's V3 curve and its V2 pair.
+    address internal pool;
+    address internal pair;
+
+    // fresh labels only: well known test addresses are EIP-7702 sweepers on BNB Chain
+    address internal dev = makeAddr("kit.dev");
+    address internal alice = makeAddr("kit.alice");
+    address internal bob = makeAddr("kit.bob");
+    address internal carol = makeAddr("kit.carol");
+    address internal dave = makeAddr("kit.dave");
+    address internal erin = makeAddr("kit.erin");
+
+    uint256 private salt_;
+
+    /// @notice Your mode, built for the live factory: `return address(new MyMode(Live.FACTORY));`
+    function deployMode() internal virtual returns (address);
+
+    function setUp() public virtual {
+        string memory rpc = vm.envOr("FORK_RPC", string(""));
+        if (bytes(rpc).length == 0) rpc = vm.envOr("BSC_RPC_URL", string(""));
+        require(bytes(rpc).length != 0, "set BSC_RPC_URL to a BNB Chain RPC (or FORK_RPC to a local fork)");
+        uint256 blk = vm.envOr("FORK_BLOCK", uint256(0));
+        if (blk == 0) vm.createSelectFork(rpc);
+        else vm.createSelectFork(rpc, blk);
+        require(block.chainid == 56, "the RPC is not BNB Chain");
+
+        factory = IStickyFactory3(Live.FACTORY);
+        mode = deployMode();
+        require(mode.code.length != 0, "deployMode returned no contract");
+        vm.prank(factory.owner());
+        factory.setMode(mode, true);
+
+        address[6] memory people = [dev, alice, bob, carol, dave, erin];
+        for (uint256 i; i < people.length; i++) {
+            vm.deal(people[i], 100 ether);
+        }
+    }
+
+    // ------------------------------------------------ launching
+
+    /// @notice Launches a coin with your mode and these settings (empty: the mode's defaults). No first buy.
+    function launch(bytes memory data) internal returns (IStickyCoin3Live) {
+        return launch(data, 0);
+    }
+
+    /// @notice The same with the creator's first buy of `devBuy` BNB (it runs through the mode like any buy).
+    function launch(bytes memory data, uint256 devBuy) internal returns (IStickyCoin3Live) {
+        IStickyFactory3.LaunchArgs memory a = launchArgs(data);
+        uint256 value = factory.seedBnb() + devBuy;
+        vm.prank(dev, dev);
+        coin = IStickyCoin3Live(factory.launch{value: value}(a));
+        pool = coin.pool();
+        pair = coin.pool2();
+        return coin;
+    }
+
+    /// @notice The factory refuses these settings (your quote() reverts, or the share of buys is over the cap).
+    function expectLaunchRevert(bytes memory data) internal {
+        IStickyFactory3.LaunchArgs memory a = launchArgs(data);
+        uint256 seed = factory.seedBnb();
+        vm.prank(dev, dev);
+        vm.expectRevert();
+        factory.launch{value: seed}(a);
+    }
+
+    function launchArgs(bytes memory data) internal returns (IStickyFactory3.LaunchArgs memory a) {
+        a.name = "Kit Test";
+        a.symbol = "KIT";
+        a.metadata = "";
+        a.rows = new uint256[](0);
+        a.salt = keccak256(abi.encode("mode kit", salt_++));
+        a.keepBps = 10_000;
+        a.mode = mode;
+        a.modeData = data;
+    }
+
+    // ------------------------------------------------ trading the way terminals do
+
+    /// @notice A buy through PancakeSwap's V3 router (the coin's curve), from a wallet. Returns the coins out.
+    function routerBuy(address who, uint256 bnb) internal returns (uint256) {
+        vm.prank(who, who);
+        return ISwapRouterV3(Live.ROUTER_V3).exactInputSingle{value: bnb}(
+            ISwapRouterV3.ExactInputSingleParams(Live.WBNB, address(coin), 10_000, who, block.timestamp, bnb, 0, 0)
+        );
+    }
+
+    /// @notice A sell through the V3 router. Returns the BNB (as WBNB) out.
+    function routerSell(address who, uint256 coins) internal returns (uint256 out) {
+        vm.startPrank(who, who);
+        coin.approve(Live.ROUTER_V3, coins);
+        out = ISwapRouterV3(Live.ROUTER_V3).exactInputSingle(
+            ISwapRouterV3.ExactInputSingleParams(address(coin), Live.WBNB, 10_000, who, block.timestamp, coins, 0, 0)
+        );
+        vm.stopPrank();
+    }
+
+    /// @notice A buy through the V2 router (the coin's V2 pair).
+    function v2Buy(address who, uint256 bnb) internal {
+        address[] memory path = new address[](2);
+        (path[0], path[1]) = (Live.WBNB, address(coin));
+        vm.prank(who, who);
+        IRouterV2(Live.ROUTER_V2).swapExactETHForTokensSupportingFeeOnTransferTokens{value: bnb}(
+            0, path, who, block.timestamp
+        );
+    }
+
+    /// @notice A sell through the V2 router.
+    function v2Sell(address who, uint256 coins) internal {
+        address[] memory path = new address[](2);
+        (path[0], path[1]) = (address(coin), Live.WBNB);
+        vm.startPrank(who, who);
+        coin.approve(Live.ROUTER_V2, coins);
+        IRouterV2(Live.ROUTER_V2).swapExactTokensForETHSupportingFeeOnTransferTokens(coins, 0, path, who, block.timestamp);
+        vm.stopPrank();
+    }
+
+    /// @notice An exact buy of `coins` straight out of the curve, for tests that need round numbers. The coin only counts
+    ///         a pool transfer as a trade when the price moved, so this nudges the pool's price first.
+    function curveBuy(address who, uint256 coins) internal {
+        _nudge();
+        vm.prank(pool, who);
+        coin.transfer(who, coins);
+    }
+
+    /// @notice An exact sell of `coins` into the curve.
+    function curveSell(address who, uint256 coins) internal {
+        _nudge();
+        vm.prank(who, who);
+        coin.transfer(pool, coins);
+    }
+
+    function send(address from, address to, uint256 coins) internal {
+        vm.prank(from, from);
+        coin.transfer(to, coins);
+    }
+
+    /// @notice A holder's move (your `_play`): `abi.encode(uint8 action, ...)`.
+    function play(address who, bytes memory data) internal {
+        vm.prank(who, who);
+        coin.play(data);
+    }
+
+    /// @notice Anyone's nudge (your `_poke`), sent by a wallet that holds nothing.
+    function poke(bytes memory data) internal {
+        address k = makeAddr("kit.keeper");
+        vm.prank(k, k);
+        coin.poke(data);
+    }
+
+    function wait(uint256 secs) internal {
+        vm.warp(vm.getBlockTimestamp() + secs);
+        vm.roll(block.number + secs * 100 / 45 + 1);
+    }
+
+    function _nudge() private {
+        bytes32 s = vm.load(pool, bytes32(0));
+        vm.store(pool, bytes32(0), bytes32(uint256(s) + 1));
+    }
+
+    // ------------------------------------------------ units
+
+    /// @notice `b` basis points of the supply, in coins.
+    function bps(uint256 b) internal pure returns (uint256) {
+        return SUPPLY * b / 10_000;
+    }
+
+    /// @notice `p` millionths of the supply, in coins.
+    function ppm(uint256 p) internal pure returns (uint256) {
+        return SUPPLY * p / 1e6;
+    }
+
+    function held(address who) internal view returns (uint256 a) {
+        (a,,,) = coin.heldOf(who);
+    }
+
+    // ------------------------------------------------ the guardrails every mode keeps
+
+    /// @notice A launch with `data` and trades on every path a terminal takes: V3 and V2 buys (one by the creator),
+    ///         sends, V3 and V2 sells, an hour apart. Checks that sends and sells take nothing, the coin never skipped the
+    ///         mode, the pot is backed, and the mode stays under 200,000 gas on a buy, a sell and a send.
+    function guardrails(bytes memory data) internal {
+        launch(data);
+        _record();
+        routerBuy(alice, 0.05 ether);
+        routerBuy(bob, 0.03 ether);
+        v2Buy(carol, 0.02 ether);
+        routerBuy(dev, 0.01 ether);
+        wait(1 hours);
+        routerBuy(dave, 0.02 ether);
+
+        uint256 a = coin.balanceOf(alice);
+        uint256 e = coin.balanceOf(erin);
+        uint256 s = a / 10;
+        send(alice, erin, s);
+        assertGe(coin.balanceOf(erin), e + s, "a send arrives in full");
+        assertGe(coin.balanceOf(alice) + s, a, "a send takes nothing more than the coins sent");
+
+        uint256 pot = coin.gamePot();
+        uint256 b = coin.balanceOf(bob);
+        assertGt(routerSell(bob, b / 2), 0, "a V3 sell pays out");
+        assertLe(coin.gamePot(), pot, "a sell puts nothing into the pot");
+        assertGe(coin.balanceOf(bob) + b / 2, b, "a sell takes nothing more than the coins sold");
+        v2Sell(carol, coin.balanceOf(carol) / 2);
+
+        assertBooks();
+        assertNoSkips();
+        assertModeGas(BUY, dave, ppm(1000));
+        assertModeGas(SELL, alice, ppm(1000));
+        assertModeGas(SEND, alice, ppm(1000));
+    }
+
+    /// @notice `n` trades by five wallets, buys, sells and sends of changing sizes over changing times, then the same
+    ///         checks. Finds the loop that grows, the counter that overflows, the branch that reverts.
+    function stress(bytes memory data, uint256 n) internal {
+        launch(data);
+        _record();
+        address[5] memory w = [alice, bob, carol, dave, erin];
+        for (uint256 i; i < n; i++) {
+            uint256 r = uint256(keccak256(abi.encode("stress", i)));
+            address who = w[r % 5];
+            uint256 kind = (r >> 8) % 6;
+            uint256 bal = coin.balanceOf(who);
+            if (kind <= 2 || bal == 0) {
+                uint256 bnb = 0.001 ether + (r >> 16) % 0.03 ether;
+                if (kind == 1) v2Buy(who, bnb);
+                else routerBuy(who, bnb);
+            } else if (kind == 3) {
+                routerSell(who, bal * (10 + (r >> 24) % 80) / 100);
+            } else if (kind == 4) {
+                v2Sell(who, bal * (10 + (r >> 24) % 80) / 100);
+            } else {
+                address to = w[(r >> 32) % 5];
+                if (to == who) to = w[((r >> 32) + 1) % 5];
+                send(who, to, bal / 5);
+            }
+            if ((r >> 40) % 4 == 0) wait(60 + (r >> 48) % 4 hours);
+        }
+        assertBooks();
+        assertNoSkips();
+        assertModeGas(BUY, alice, ppm(1000));
+        assertModeGas(SELL, bob, ppm(1000));
+        assertModeGas(SEND, carol, ppm(1000));
+    }
+
+    /// @notice The gas your mode uses for one trade of this kind, in the coin's current state (the mode's state is
+    ///         rolled back after). `who` trades `coins`.
+    function modeGas(uint8 kind, address who, uint256 coins) internal returns (uint256 used) {
+        IStickyMode.Trade memory t = IStickyMode.Trade({
+            kind: kind,
+            from: kind == BUY ? pool : who,
+            to: kind == BUY ? who : (kind == SELL ? pool : erin),
+            who: who,
+            amount: coins,
+            got: coins,
+            dev: 0,
+            sniper: 0,
+            pot: coin.gamePot(),
+            buys: 1_000
+        });
+        uint256 snap = vm.snapshotState();
+        vm.prank(address(coin));
+        uint256 g = gasleft();
+        IStickyMode(mode).onTrade(t);
+        used = g - gasleft();
+        vm.revertToState(snap);
+    }
+
+    function assertModeGas(uint8 kind, address who, uint256 coins) internal {
+        uint256 used = modeGas(kind, who, coins);
+        assertLe(used, MODE_GAS_LIMIT, "the mode uses more than 200,000 gas on a trade");
+    }
+
+    /// @notice The game pot is backed by coins the coin holds.
+    function assertBooks() internal view {
+        assertGe(coin.balanceOf(address(coin)), coin.gamePot(), "the pot is not backed by coins");
+    }
+
+    /// @notice Since the launch (or the last check) the coin never skipped the mode: no revert, no out of gas, no
+    ///         malformed answer on any trade.
+    function assertNoSkips() internal {
+        Vm.Log[] memory logs = vm.getRecordedLogs();
+        for (uint256 i; i < logs.length; i++) {
+            if (logs[i].emitter == address(coin) && logs[i].topics.length != 0 && logs[i].topics[0] == MODE_SKIPPED) {
+                assertTrue(false, "the coin skipped the mode on a trade: it reverted, ran out of gas or answered garbage");
+            }
+        }
+        _record();
+    }
+
+    function _record() private {
+        vm.recordLogs();
+    }
+}

package/lib/abi.mjs

@@ -0,0 +1,117 @@
+// A small ABI encoder (abi.encode), enough for mode settings, plays and pokes: uint<N>, int<N>, bool, address,
+// bytes<N>, bytes, string and arrays of them. No dependencies, so the kit runs with node alone.
+
+const WORD = 64; // hex chars
+
+const pad = (hex) => hex.padStart(WORD, "0");
+const padRight = (hex) => hex.padEnd(Math.ceil(hex.length / WORD) * WORD || WORD, "0");
+
+export function isDynamic(type) {
+  return type === "bytes" || type === "string" || type.endsWith("[]");
+}
+
+export function isStatic(type) {
+  return !isDynamic(type) && /^(u?int(8|16|24|32|40|48|56|64|72|80|88|96|104|112|120|128|136|144|152|160|168|176|184|192|200|208|216|224|232|240|248|256)?|bool|address|bytes([1-9]|[12][0-9]|3[0-2]))$/.test(type);
+}
+
+export function isType(type) {
+  if (type.endsWith("[]")) return isType(type.slice(0, -2));
+  return type === "bytes" || type === "string" || isStatic(type);
+}
+
+function bits(type) {
+  const m = /^u?int(\d+)?$/.exec(type);
+  return m ? Number(m[1] ?? 256) : 256;
+}
+
+/** A value as a BigInt: 123, "123", "0x7b", "1.5" with decimals 18, "1e18". */
+export function toBig(v, decimals = 0) {
+  if (typeof v === "bigint") return v;
+  if (typeof v === "boolean") return v ? 1n : 0n;
+  if (typeof v === "number") {
+    if (!Number.isFinite(v)) throw new Error(`not a number: ${v}`);
+    v = Number.isInteger(v) && decimals === 0 ? BigInt(v).toString() : String(v);
+  }
+  const s = String(v).trim().replace(/_/g, "");
+  if (/^-?0x[0-9a-f]+$/i.test(s)) return s.startsWith("-") ? -BigInt(s.slice(1)) : BigInt(s);
+  const e = /^(-?)(\d+)(?:\.(\d+))?(?:e\+?(\d+))?$/i.exec(s);
+  if (!e) throw new Error(`not a number: ${v}`);
+  const [, neg, int, frac = "", exp = "0"] = e;
+  // the value is int.frac x 10^shift: the integer digits followed by the fraction padded to `shift` digits
+  const shift = Number(exp) + decimals;
+  if (frac.length > shift) throw new Error(`${v} has more decimals than ${shift}`);
+  const n = BigInt(int + frac.padEnd(shift, "0"));
+  return neg ? -n : n;
+}
+
+function encStatic(type, v) {
+  if (type === "bool") {
+    const b = v === true || v === "true" || v === 1 || v === "1" || v === 1n;
+    const f = v === false || v === "false" || v === 0 || v === "0" || v === 0n;
+    if (!b && !f) throw new Error(`bool expects true or false, got ${v}`);
+    return pad(b ? "1" : "0");
+  }
+  if (type === "address") {
+    const s = String(v);
+    if (!/^0x[0-9a-fA-F]{40}$/.test(s)) throw new Error(`not an address: ${v}`);
+    return pad(s.slice(2).toLowerCase());
+  }
+  const bm = /^bytes(\d+)$/.exec(type);
+  if (bm) {
+    const n = Number(bm[1]);
+    const s = String(v);
+    if (!/^0x[0-9a-fA-F]*$/.test(s) || (s.length - 2) / 2 !== n) throw new Error(`${type} expects ${n} bytes of hex, got ${v}`);
+    return padRight(s.slice(2).toLowerCase());
+  }
+  const n = toBig(v);
+  const b = bits(type);
+  if (type.startsWith("uint")) {
+    if (n < 0n || n >= 1n << BigInt(b)) throw new Error(`${v} does not fit ${type}`);
+    return pad(n.toString(16));
+  }
+  const lim = 1n << BigInt(b - 1);
+  if (n < -lim || n >= lim) throw new Error(`${v} does not fit ${type}`);
+  return pad((n < 0n ? (1n << 256n) + n : n).toString(16));
+}
+
+function encDynamic(type, v) {
+  if (type === "bytes" || type === "string") {
+    let hex;
+    if (type === "string") hex = Buffer.from(String(v), "utf8").toString("hex");
+    else {
+      const s = String(v);
+      if (!/^0x([0-9a-fA-F]{2})*$/.test(s)) throw new Error(`bytes expects hex, got ${v}`);
+      hex = s.slice(2).toLowerCase();
+    }
+    return pad((hex.length / 2).toString(16)) + (hex.length ? padRight(hex) : "");
+  }
+  const inner = type.slice(0, -2);
+  const arr = Array.isArray(v) ? v : JSON.parse(String(v));
+  if (!Array.isArray(arr)) throw new Error(`${type} expects an array`);
+  return pad(arr.length.toString(16)) + encodeTuple(arr.map(() => inner), arr);
+}
+
+function encodeTuple(types, values) {
+  if (types.length !== values.length) throw new Error(`expected ${types.length} values, got ${values.length}`);
+  const heads = [];
+  const tails = [];
+  let tailLen = 0;
+  const headLen = types.length * 32;
+  for (let i = 0; i < types.length; i++) {
+    if (isDynamic(types[i])) {
+      const t = encDynamic(types[i], values[i]);
+      heads.push(pad((headLen + tailLen).toString(16)));
+      tails.push(t);
+      tailLen += t.length / 2;
+    } else {
+      heads.push(encStatic(types[i], values[i]));
+    }
+  }
+  return heads.join("") + tails.join("");
+}
+
+/** abi.encode(values...) of these types, as 0x hex. */
+export function encode(types, values) {
+  for (const t of types) if (!isType(t)) throw new Error(`the kit cannot encode the type ${t}`);
+  return "0x" + encodeTuple(types, values);
+}