@pickhooks/sdk 0.0.0-stage → 0.4.0

package/dist/coins.js

@@ -0,0 +1,520 @@
+import { encodeFunctionData, isAddressEqual, parseAbi, parseEventLogs } from "viem";
+import { pancakeV2FactoryAbi, v3PoolAbi } from "./abis/common.js";
+import { v1BuySimCode, v1FactoryAbi, v1LockerAbi, v1TokenAbi } from "./abis/v1.js";
+import { arenaAbi, floorVaultAbi, payrollBoxAbi, v2FactoryAbi, v2LockerAbi, v2TokenAbi, voteBoxAbi } from "./abis/v2.js";
+import { ZERO_ADDRESS } from "./addresses.js";
+import { RULE_BY_KIND, buildRules, emptyExtras, kindsOf, launchPots, selectionProblem, worstScanner } from "./coin-rules.js";
+import { PickhooksError, explain, toPickhooksError } from "./errors.js";
+import { blockedKind } from "./infinity.js";
+import { minusBps, sendTx, signer } from "./tx.js";
+import { approvalFor, buildV3Buy, buildV3Sell, receivedOf, v3EstimateBuy, v3PriceBnb, v3Quote } from "./v3.js";
+const simAbi = parseAbi(["function sim(address token, address to, uint256 amount)"]);
+const pancakeV2RouterAbi = parseAbi(["function getAmountsIn(uint256 amountOut, address[] path) view returns (uint256[] amounts)"]);
+const erc20Transfer = parseAbi(["function transfer(address to, uint256 amount) returns (bool)"]);
+const randomSalt = () => {
+    const b = new Uint8Array(32);
+    globalThis.crypto.getRandomValues(b);
+    return `0x${Array.from(b, (x) => x.toString(16).padStart(2, "0")).join("")}`;
+};
+/** A rule's sentence for a refusal: its name and the rule with the coin's numbers. */
+export function ruleText(kind, rules, extras) {
+    const def = RULE_BY_KIND.get(kind);
+    if (!def)
+        return { name: `Rule ${kind}`, text: `Refused by rule ${kind}.` };
+    let line = def.line;
+    if (rules) {
+        try {
+            line = def.describe(rules, extras ?? undefined);
+        }
+        catch {
+            /* a v2 rule read without its extras */
+        }
+    }
+    return { name: def.name, text: `Refused by the rule "${def.name}". ${line}` };
+}
+export function coinsModule(ctx) {
+    const { pub, a } = ctx;
+    const ABI = { 1: v1TokenAbi, 2: v2TokenAbi };
+    const FACTORY = {
+        1: { address: a.coinsV1Factory, abi: v1FactoryAbi },
+        2: { address: a.coinsV2Factory, abi: v2FactoryAbi },
+    };
+    const versions = new Map();
+    const call = (address, abi, functionName, args = []) => pub.readContract({ address, abi, functionName, args });
+    /** 2 for a v2 coin, 1 for a v1 coin, null for neither. */
+    async function versionOf(token) {
+        const hit = versions.get(token.toLowerCase());
+        if (hit)
+            return hit;
+        for (const v of [2, 1]) {
+            const is = await call(FACTORY[v].address, FACTORY[v].abi, "isCoin", [token]).catch(() => false);
+            if (is) {
+                versions.set(token.toLowerCase(), v);
+                return v;
+            }
+        }
+        return null;
+    }
+    async function need(token) {
+        const v = await versionOf(token);
+        if (!v)
+            throw new PickhooksError("This is not a pickhooks coin with rules in the coin.", { code: "input" });
+        return v;
+    }
+    /** How many coins a factory launched. */
+    const count = async (version = 2) => Number(await call(FACTORY[version].address, FACTORY[version].abi, "coinCount"));
+    async function tokensOf(version, limit, offset) {
+        const n = await count(version);
+        const end = Math.max(0, n - offset);
+        const from = Math.max(0, end - limit);
+        if (end <= from)
+            return [];
+        const list = (await pub.multicall({
+            contracts: Array.from({ length: end - from }, (_, i) => ({ address: FACTORY[version].address, abi: FACTORY[version].abi, functionName: "coins", args: [BigInt(end - 1 - i)] })),
+            allowFailure: false,
+        }));
+        for (const t of list)
+            versions.set(t.toLowerCase(), version);
+        return list;
+    }
+    /** Coins newest first: `limit` of each version (v2 and v1 merged by launch time, or one version). */
+    async function coins(o = {}) {
+        const vs = o.version ? [o.version] : [2, 1];
+        const lists = await Promise.all(vs.map(async (v) => summaries(v, await tokensOf(v, o.limit ?? 50, o.offset ?? 0))));
+        return lists.flat().sort((x, y) => y.start - x.start);
+    }
+    /** One coin, or null when it is not one of the two factories' coins. */
+    async function coin(token) {
+        const v = await versionOf(token);
+        if (!v)
+            return null;
+        return (await summaries(v, [token]))[0] ?? null;
+    }
+    const FIELDS = ["name", "symbol", "metadata", "creator", "pool", "pool2", "start", "rules", "stats", "curveSupply", "jackpotPot", "jackpotLast", "jackpotTime", "rewardsPot"];
+    async function summaries(version, tokens) {
+        if (!tokens.length)
+            return [];
+        const abi = ABI[version];
+        const per = FIELDS.length;
+        const [res, head] = await Promise.all([
+            pub.multicall({ contracts: tokens.flatMap((t) => FIELDS.map((functionName) => ({ address: t, abi, functionName }))), allowFailure: true }),
+            pub.getBlock({ blockTag: "latest" }),
+        ]);
+        const now = Number(head.timestamp);
+        const pools = tokens.map((_, i) => res[i * per + 4].result);
+        const masks = tokens.map((_, i) => (res[i * per + 7].result?.mask ?? 0n));
+        const kindsAll = masks.map((m) => kindsOf(m));
+        const [slots, untils, offs] = await Promise.all([
+            pub.multicall({ contracts: pools.map((p) => ({ address: (p ?? a.wbnb), abi: v3PoolAbi, functionName: "slot0" })), allowFailure: true }),
+            pub.multicall({
+                contracts: tokens.flatMap((t, i) => kindsAll[i].map((k) => ({ address: t, abi, functionName: "until", args: [k] }))),
+                allowFailure: true,
+            }),
+            version === 2 ? pub.multicall({ contracts: tokens.map((t) => ({ address: t, abi, functionName: "off" })), allowFailure: true }) : Promise.resolve([]),
+        ]);
+        const extrasAll = version === 2 ? await Promise.all(tokens.map((t, i) => extrasOf(t, masks[i]).catch(() => null))) : tokens.map(() => null);
+        const out = [];
+        let u = 0;
+        tokens.forEach((token, i) => {
+            const g = (k) => res[i * per + k];
+            const kinds = kindsAll[i];
+            const untilOf = kinds.map(() => untils[u++]);
+            if (g(0).status !== "success" || !pools[i] || g(7).status !== "success")
+                return;
+            const rules = g(7).result;
+            const stats = g(8).result;
+            const curve = g(9).result ?? 0n;
+            const off = version === 2 && offs[i]?.status === "success" ? kindsOf(offs[i].result) : [];
+            const x = extrasAll[i];
+            const sl = slots[i];
+            const priceBnb = sl.status === "success" ? v3PriceBnb(sl.result[0], token, a.wbnb) : 0;
+            out.push({
+                token,
+                version,
+                name: String(g(0).result ?? ""),
+                symbol: String(g(1).result ?? ""),
+                metadata: String(g(2).result ?? ""),
+                creator: g(3).result,
+                pool: pools[i],
+                pair: g(5).result ?? ZERO_ADDRESS,
+                start: Number(g(6).result ?? 0),
+                rules: kinds.map((kind, j) => {
+                    const def = RULE_BY_KIND.get(kind);
+                    const until = untilOf[j]?.status === "success" ? Number(untilOf[j].result) : 0;
+                    let text = def?.line ?? "";
+                    try {
+                        if (def)
+                            text = def.describe(rules, x ?? undefined);
+                    }
+                    catch {
+                        /* keep the line */
+                    }
+                    return { kind, name: def?.name ?? `Rule ${kind}`, text, scanner: def?.scanner.level ?? "green", until, ended: off.includes(kind) || (until !== 0 && now >= until) };
+                }),
+                scanner: worstScanner(kinds),
+                raw: rules,
+                extras: x,
+                holders: Number(stats[0]),
+                buys: Number(stats[1]),
+                sells: Number(stats[2]),
+                soldBps: curve ? Number((stats[11] * 10000n) / curve) : 0,
+                jackpotPot: g(10).result ?? 0n,
+                jackpotLast: g(11).result ?? ZERO_ADDRESS,
+                jackpotTime: Number(g(12).result ?? 0),
+                rewardsPot: g(13).result ?? 0n,
+                priceBnb,
+                mcapBnb: priceBnb * 1e9,
+                chainNow: now,
+            });
+        });
+        return out;
+    }
+    let termsCache = null;
+    /** The v2 factory's terms and its companions (vote box, duel arena, floor vault, payroll box, locker). */
+    function terms() {
+        termsCache ??= (async () => {
+            const fns = ["hooksBurn", "creatorBps", "seedBnb", "hooks", "voteBox", "arena", "floorVault", "payrollBox", "locker"];
+            const r = await pub.multicall({ contracts: fns.map((functionName) => ({ address: a.coinsV2Factory, abi: FACTORY[2].abi, functionName })), allowFailure: false });
+            return { hooksBurn: r[0], creatorBps: Number(r[1]), seedBnb: r[2], hooks: r[3], voteBox: r[4], arena: r[5], floorVault: r[6], payrollBox: r[7], locker: r[8] };
+        })().catch((e) => {
+            termsCache = null;
+            throw e;
+        });
+        return termsCache;
+    }
+    /** The v2 settings a coin launched with: what its v2 rules' sentences and buttons need. */
+    async function extrasOf(token, mask) {
+        const has = (k) => (mask & (1n << BigInt(k))) !== 0n;
+        const fns = ["buyoutMask", "votable", "quorumBps", "voteSeconds", "feed", "target", "sellsAtSeconds", "deadManSeconds", "payrollMin"];
+        const r = await pub.multicall({ contracts: fns.map((functionName) => ({ address: token, abi: ABI[2], functionName })), allowFailure: false });
+        const x = {
+            ...emptyExtras(),
+            buyoutMask: r[0],
+            votable: r[1],
+            quorumBps: Number(r[2]),
+            voteSeconds: Number(r[3]),
+            feed: r[4],
+            target: r[5],
+            sellsAtSeconds: Number(r[6]),
+            deadManSeconds: Number(r[7]),
+            payrollMin: r[8],
+        };
+        const buyable = kindsOf(x.buyoutMask);
+        if (buyable.length) {
+            const prices = (await pub.multicall({ contracts: buyable.map((k) => ({ address: token, abi: ABI[2], functionName: "buyoutPrice", args: [k] })), allowFailure: false }));
+            x.buyoutPrice = [0, 1, 2, 3, 4, 5, 6, 7].map((j) => prices[j] ?? 0n);
+        }
+        if (has(41) || has(45) || has(46)) {
+            const t = await terms();
+            if (has(41)) {
+                const id = await call(t.arena, arenaAbi, "duelOf", [token]);
+                if (id > 0n) {
+                    const d = await call(t.arena, arenaAbi, "get", [id]);
+                    x.duelStake = d.stake;
+                    x.duelOpponent = isAddressEqual(d.b, token) ? d.a : ZERO_ADDRESS;
+                }
+            }
+            if (has(45)) {
+                const f = await call(t.floorVault, floorVaultAbi, "floors", [token]);
+                x.floorDeposit = f[0];
+                x.floorBps = Number(f[2]);
+            }
+            if (has(46)) {
+                const c = await call(t.payrollBox, payrollBoxAbi, "coins", [token]);
+                x.shiftSeconds = Number(c[5]);
+            }
+        }
+        return x;
+    }
+    // ------------------------------------------------ the dry runs
+    /**
+     * v2 coins count a transfer with the V3 pool as a trade only when the pool's price moved since the last counted trade,
+     * so the dry runs nudge the pool's slot0 by one through a state override, like a swap would.
+     */
+    async function nudged(pool) {
+        const slot0 = await pub.getStorageAt({ address: pool, slot: "0x0" });
+        const value = `0x${(BigInt(slot0 ?? "0x0") + 1n).toString(16).padStart(64, "0")}`;
+        return [{ address: pool, stateDiff: [{ slot: `0x${"0".repeat(64)}`, value }] }];
+    }
+    /**
+     * Would this trade go through: the coin's own transfer of the trade in an eth_call (a buy: the coins leaving the pool
+     * to the wallet, a sell: the wallet's coins into the pool, a send: wallet to `to`). For a buy pass the coins it would get
+     * (quote()). The refusal names the rule with the coin's numbers.
+     */
+    async function check(c) {
+        const v = await need(c.token);
+        const abi = ABI[v];
+        const pool = await call(c.token, abi, "pool");
+        const transfer = (to, amount) => encodeFunctionData({ abi: erc20Transfer, functionName: "transfer", args: [to, amount] });
+        try {
+            if (c.side === "send") {
+                await pub.call({ account: c.wallet, to: c.token, data: transfer(c.to ?? ZERO_ADDRESS, c.amount) });
+            }
+            else if (v === 2) {
+                const override = await nudged(pool);
+                if (c.side === "buy")
+                    await pub.call({ account: pool, to: c.token, data: transfer(c.wallet, c.amount), stateOverride: override });
+                else
+                    await pub.call({ account: c.wallet, to: c.token, data: transfer(pool, c.amount), stateOverride: override });
+            }
+            else if (c.side === "buy") {
+                // v1: a tiny forwarder on the pool's address moves the coins out exactly as a real buy would (msg.sender = pool,
+                // tx.origin = buyer), for this one eth_call
+                await pub.call({
+                    account: c.wallet,
+                    to: pool,
+                    data: encodeFunctionData({ abi: simAbi, functionName: "sim", args: [c.token, c.wallet, c.amount] }),
+                    stateOverride: [{ address: pool, code: v1BuySimCode }],
+                });
+            }
+            else {
+                await pub.call({ account: c.wallet, to: c.token, data: transfer(pool, c.amount) });
+            }
+            return { ok: true };
+        }
+        catch (e) {
+            const kind = blockedKind(e);
+            if (kind === null)
+                return { ok: false, kind: 0, name: "", text: explain(e, "The coin refused this transfer.").text };
+            const rules = await call(c.token, abi, "rules");
+            const x = v === 2 ? await extrasOf(c.token, rules.mask).catch(() => null) : null;
+            return { ok: false, kind, ...ruleText(kind, rules, x) };
+        }
+    }
+    /** a contract refusal of one of these coins as a sentence that names the rule */
+    async function refusalOf(token, e, fallback) {
+        const kind = blockedKind(e);
+        if (kind === null)
+            return toPickhooksError(e, fallback);
+        const v = await need(token);
+        const rules = await call(token, ABI[v], "rules").catch(() => null);
+        const r = ruleText(kind, rules);
+        return new PickhooksError(r.text, { code: "Blocked", args: [kind], cause: e });
+    }
+    /** Coins a buy of `bnbIn` would get, estimated from the pool's liquidity at its price (see v3EstimateBuy); not a minOut. */
+    async function estimateBuy(token, bnbIn) {
+        const pool = await call(token, ABI[await need(token)], "pool");
+        return v3EstimateBuy(ctx, pool, token, bnbIn);
+    }
+    /**
+     * What a trade gets in the V3 pool, from PancakeSwap's QuoterV2. A buy a rule refuses fails in the quoter without the
+     * reason, so it is checked again with an estimate of its coins and the refusal names the rule (for `wallet`, by default
+     * the quoter the quote ran as).
+     */
+    async function quote(q) {
+        try {
+            return { amountOut: await v3Quote(ctx, q) };
+        }
+        catch (e) {
+            if (q.side === "buy" && blockedKind(e) === null) {
+                const est = await estimateBuy(q.token, q.amount).catch(() => 0n);
+                const c = est > 0n ? await check({ token: q.token, side: "buy", wallet: q.wallet ?? a.v3Quoter, amount: est }).catch(() => null) : null;
+                if (c && !c.ok && c.kind > 0)
+                    throw new PickhooksError(c.text, { code: "Blocked", args: [c.kind], cause: e });
+            }
+            throw await refusalOf(q.token, e, "The quoter refused this trade.");
+        }
+    }
+    const refuse = (c) => {
+        if (!c.ok)
+            throw new PickhooksError(c.text, { code: "Blocked", args: [c.kind] });
+    };
+    /** Quotes, checks the coin's rules for this wallet, and buys through PancakeSwap V3. A refusing rule stops it before anything is signed. */
+    async function buy(b, s = {}) {
+        const { address } = await signer(ctx, s.wallet);
+        const q = await quote({ token: b.token, side: "buy", amount: b.bnbIn, wallet: address });
+        refuse(await check({ token: b.token, side: "buy", wallet: address, amount: q.amountOut }));
+        const minOut = b.minOut ?? minusBps(q.amountOut, b.slippageBps ?? 100);
+        try {
+            const sent = await sendTx(ctx, buildV3Buy(a, { token: b.token, bnbIn: b.bnbIn, minOut, recipient: address, deadline: b.deadline, gasPct: 150 }), s);
+            return { ...sent, quoted: q.amountOut, minOut, amountOut: receivedOf(sent.receipt, b.token, address) };
+        }
+        catch (e) {
+            throw await refusalOf(b.token, e, "The buy would fail.");
+        }
+    }
+    /** Checks the rules, approves the V3 router if needed, quotes and sells for BNB. */
+    async function sell(x, s = {}) {
+        const { address } = await signer(ctx, s.wallet);
+        refuse(await check({ token: x.token, side: "sell", wallet: address, amount: x.amount }));
+        const ap = await approvalFor(ctx, address, x.token, x.amount, a.v3Router, "Allowing PancakeSwap");
+        if (ap)
+            await sendTx(ctx, ap, s);
+        const q = await quote({ token: x.token, side: "sell", amount: x.amount });
+        const minOut = x.minOut ?? minusBps(q.amountOut, x.slippageBps ?? 100);
+        try {
+            const sent = await sendTx(ctx, buildV3Sell(a, { token: x.token, amount: x.amount, minOut, recipient: address, deadline: x.deadline, gasPct: 150 }), s);
+            return { ...sent, quoted: q.amountOut, minOut };
+        }
+        catch (e) {
+            throw await refusalOf(x.token, e, "The sell would fail.");
+        }
+    }
+    // ------------------------------------------------ launch (v2 factory)
+    /** $hooks the launch burns for these rules, and the BNB the factory needs to buy them (quote + 3 % tax + 5 % room). */
+    async function burnFor(mask) {
+        const hooks = await call(a.coinsV2Factory, FACTORY[2].abi, "burnFor", [mask]);
+        if (hooks === 0n)
+            return { hooks, bnb: 0n };
+        const want = (hooks * 10000n) / 9500n;
+        const [bnbIn] = await call(a.v2Router, pancakeV2RouterAbi, "getAmountsIn", [want, [a.wbnb, a.hooks]]);
+        return { hooks, bnb: (bnbIn * 105n) / 100n };
+    }
+    /**
+     * Launches a coin with up to eight rules on the v2 factory: checks the selection like the factory, builds the Rules and
+     * Extras structs, pays the $hooks burn of hooks rules (in BNB or $hooks), sends the seed, the deposits (duel stake,
+     * floor, payroll) and the first buy, then funds a jackpot or rewards pot the rules ask for. Gas: estimate + 5 %, never
+     * above BNB Chain's cap (a launch needs about 14.4M).
+     */
+    async function launch(l, s = {}) {
+        const problem = selectionProblem(l.rules);
+        if (problem)
+            throw new PickhooksError(problem, { code: "input" });
+        const { address } = await signer(ctx, s.wallet);
+        const now = Number((await pub.getBlock({ blockTag: "latest" })).timestamp);
+        const built = buildRules(l.rules, now, l.keepBps ?? 10_000);
+        const t = await terms();
+        const burn = await burnFor(built.rules.mask);
+        const payInHooks = burn.hooks > 0n && l.payBurnIn === "hooks";
+        if (payInHooks) {
+            const ap = await approvalFor(ctx, address, a.hooks, burn.hooks, a.coinsV2Factory, "Allowing the factory to burn $hooks");
+            if (ap)
+                await sendTx(ctx, ap, s);
+        }
+        const burnBnb = burn.hooks > 0n && !payInHooks ? burn.bnb : 0n;
+        const deposits = await call(a.coinsV2Factory, FACTORY[2].abi, "depositsFor", [built.rules.mask, built.extras, burnBnb]);
+        const args = {
+            name: l.name,
+            symbol: l.symbol,
+            metadata: l.metadata,
+            rules: built.rules,
+            untilIds: built.untilIds,
+            untilTimes: built.untilTimes,
+            salt: l.salt ?? randomSalt(),
+            extras: built.extras,
+            burnBnb,
+            maxBurn: burn.hooks,
+            minCreatorBps: t.creatorBps,
+        };
+        const tx = { to: a.coinsV2Factory, value: (l.devBuy ?? 0n) + deposits, data: encodeFunctionData({ abi: v2FactoryAbi, functionName: "launch", args: [args] }), gasPct: 105, label: "The launch" };
+        const sent = await sendTx(ctx, tx, s);
+        const ev = parseEventLogs({ abi: v2FactoryAbi, logs: sent.receipt.logs.filter((x) => isAddressEqual(x.address, a.coinsV2Factory)) });
+        const token = ev.find((e) => e.eventName === "Launched")?.args.token;
+        if (!token)
+            throw new PickhooksError("Launched, but the coin was not found in the receipt.", { code: "receipt", hash: sent.hash });
+        versions.set(token.toLowerCase(), 2);
+        const pots = [];
+        const p = launchPots(l.rules);
+        if (p.jackpot > 0)
+            pots.push(await fundPot(token, "jackpot", BigInt(Math.round(p.jackpot * 1e9)) * 10n ** 9n, s));
+        if (p.rewards > 0)
+            pots.push(await fundPot(token, "rewards", BigInt(Math.round(p.rewards * 1e9)) * 10n ** 9n, s));
+        return { ...sent, token, burned: ev.find((e) => e.eventName === "HooksBurned")?.args.amount ?? 0n, pots };
+    }
+    // ------------------------------------------------ pots, claims, fees, v2 games
+    const tokenTx = async (token, fn, args = [], value = 0n, label) => {
+        const v = await need(token);
+        return { to: token, value, data: encodeFunctionData({ abi: ABI[v], functionName: fn, args }), gasPct: 150, label };
+    };
+    const at = (to, abi, fn, args = [], value = 0n, label) => ({
+        to,
+        value,
+        data: encodeFunctionData({ abi, functionName: fn, args }),
+        gasPct: 150,
+        label,
+    });
+    /** Funds a coin's jackpot or buyer rewards pot. */
+    async function fundPot(token, pot, wei, s = {}) {
+        const v = await need(token);
+        const fn = pot === "rewards" ? "fundRewards" : v === 2 ? "fundPot" : "fundJackpot";
+        return sendTx(ctx, await tokenTx(token, fn, [], wei, `Funding the ${pot}`), s);
+    }
+    async function lockerOf(token) {
+        const v = await need(token);
+        const address = v === 2 ? (await terms()).locker : await call(a.coinsV1Factory, FACTORY[1].abi, "locker");
+        return { address, abi: (v === 2 ? v2LockerAbi : v1LockerAbi) };
+    }
+    const build = {
+        buy: (b) => buildV3Buy(a, { ...b, gasPct: 150 }),
+        sell: (x) => buildV3Sell(a, { ...x, gasPct: 150 }),
+        /** jackpot wins and buyer rewards the coin owes the caller */
+        claim: (token) => tokenTx(token, "claim", [], 0n, "The claim"),
+        settleJackpot: (token) => tokenTx(token, "settleJackpot", [], 0n, "Settling the jackpot"),
+        /** the creator takes back rewards it paid in and nobody earned */
+        withdrawRewards: (token, wei) => tokenTx(token, "withdrawRewards", [wei], 0n, "Taking rewards back"),
+        /** anyone: collects the coin's trading fees from its locked position (creator, pot, platform; coins burned or into the pair) */
+        collect: async (token) => {
+            const l = await lockerOf(token);
+            return at(l.address, l.abi, "collect", [token], 0n, "The collect");
+        },
+        /** v2: buys a listed rule off (half to the creator, half burns $hooks); the price is the coin's buyoutPrice(kind) */
+        buyout: async (token, kind) => tokenTx(token, "buyout", [kind], await call(token, ABI[2], "buyoutPrice", [kind]), "Buying the rule off"),
+        /** v2: moves the milestone level and sells at along without a trade (anyone) */
+        poke: (token) => tokenTx(token, "poke", [], 0n, "Poke"),
+        /** v2 dead man: the creator says it is still here; release: anyone burns the bag of a quiet creator */
+        alive: (token) => tokenTx(token, "alive", [], 0n, "Still here"),
+        release: (token) => tokenTx(token, "release", [], 0n, "Release"),
+        fundPayroll: (token, wei) => tokenTx(token, "fundPayroll", [], wei, "Funding the payroll"),
+        payrollClaim: async (token) => at((await terms()).payrollBox, payrollBoxAbi, "claim", [token], 0n, "The payroll claim"),
+        payShift: async (token) => at((await terms()).payrollBox, payrollBoxAbi, "payShift", [token], 0n, "Paying the shift"),
+        floorDefend: async (token) => at((await terms()).floorVault, floorVaultAbi, "defend", [token], 0n, "Defending the floor"),
+        duelClose: async (id) => at((await terms()).arena, arenaAbi, "close", [id], 0n, "Closing the duel"),
+        duelSettle: async (id) => at((await terms()).arena, arenaAbi, "settle", [id], 0n, "Settling the duel"),
+        duelRefund: async (id) => at((await terms()).arena, arenaAbi, "refund", [id], 0n, "Refunding the duel"),
+        /** votes move coins into the vote box: approve the coin to the box first (terms().voteBox) */
+        voteStart: async (token, kind, amount) => at((await terms()).voteBox, voteBoxAbi, "start", [token, kind, amount], 0n, "Opening a vote"),
+        voteCast: async (token, kind, amount, yes) => at((await terms()).voteBox, voteBoxAbi, "vote", [token, kind, amount, yes], 0n, "The vote"),
+        voteFinish: async (token, kind) => at((await terms()).voteBox, voteBoxAbi, "finish", [token, kind], 0n, "Finishing the vote"),
+        voteWithdraw: async (token, kind, round) => at((await terms()).voteBox, voteBoxAbi, "withdraw", [token, kind, round, 0n], 0n, "Taking the vote coins back"),
+    };
+    return {
+        v1Factory: a.coinsV1Factory,
+        v2Factory: a.coinsV2Factory,
+        versionOf,
+        count,
+        coins,
+        coin,
+        terms,
+        extrasOf,
+        check,
+        quote,
+        estimateBuy,
+        burnFor,
+        build,
+        buy,
+        sell,
+        launch,
+        fundPot,
+        /** a wallet's jackpot wins and buyer rewards in a coin, and its counters there */
+        wallet: async (token, who) => {
+            const v = await need(token);
+            const r = await pub.multicall({
+                contracts: [
+                    { address: token, abi: ABI[v], functionName: "balanceOf", args: [who] },
+                    { address: token, abi: ABI[v], functionName: "owed", args: [who] },
+                    { address: token, abi: ABI[v], functionName: "wallets", args: [who] },
+                ],
+                allowFailure: false,
+            });
+            const w = r[2];
+            return { balance: r[0], owed: r[1], buys: Number(w[0]), lastBuy: Number(w[1]), lastTrade: Number(w[2]), jailUntil: Number(w[3]) };
+        },
+        /** what collect() would book now: BNB fees and coins burned (simulated) */
+        pendingFees: async (token) => {
+            const l = await lockerOf(token);
+            const r = await pub.simulateContract({ address: l.address, abi: l.abi, functionName: "collect", args: [token] });
+            const [bnb, burned] = r.result;
+            return { bnb, burned };
+        },
+        claim: async (token, s = {}) => sendTx(ctx, await build.claim(token), s),
+        settleJackpot: async (token, s = {}) => sendTx(ctx, await build.settleJackpot(token), s),
+        withdrawRewards: async (token, wei, s = {}) => sendTx(ctx, await build.withdrawRewards(token, wei), s),
+        collect: async (token, s = {}) => sendTx(ctx, await build.collect(token), s),
+        buyout: async (token, kind, s = {}) => sendTx(ctx, await build.buyout(token, kind), s),
+        poke: async (token, s = {}) => sendTx(ctx, await build.poke(token), s),
+        alive: async (token, s = {}) => sendTx(ctx, await build.alive(token), s),
+        release: async (token, s = {}) => sendTx(ctx, await build.release(token), s),
+        /** the coin's PancakeSwap V2 pair against WBNB */
+        pairOf: (token) => call(a.v2Factory, pancakeV2FactoryAbi, "getPair", [token, a.wbnb]),
+    };
+}