@pickhooks/sdk 0.2.0 → 0.4.0

package/dist/sticky.d.ts

@@ -1,6 +1,8 @@
 import { type Address, type Hex } from "viem";
-import { type EditRow, type Pick, compile } from "./sticky-rules.js";
+import { type EditRow, type Pick as RulePick, compile } from "./sticky-rules.js";
+import { type SimReport } from "./sticky-sim.js";
 import { type Ctx, type SendOptions, type Sent, type TxRequest } from "./tx.js";
+import { type Venue } from "./v2.js";
 /**
  * sticky rules: a coin whose rules stick to the coins, not to the wallet. Every buy is a lot with its time and marks, a
  * send moves lots along, so a fresh wallet takes the rules with it. The creator picks up to eight rows from templates; the
@@ -75,8 +77,10 @@ export type StickyLaunch = {
     symbol: string;
     /** a link to the coin's metadata JSON (name, symbol, description, image, website, twitter, telegram) */
     metadata: string;
-    /** templates and their numbers; or rows + release for a table built elsewhere */
-    picks?: Pick[];
+    /** templates and their numbers (numbers left out take the template's defaults); or rows + release for a table built elsewhere */
+    picks?: (Omit<RulePick, "params"> & {
+        params?: RulePick["params"];
+    })[];
     /**
      * hook script: the creator's own rows, after the templates (the factory's custom switch must be on). Built like the
      * site's editor: emptyEditRow(), VARS for the variables and their units, editToRow() for the row on chain.
@@ -92,6 +96,12 @@ export type StickyLaunch = {
     keepBps?: number;
     /** a fixed salt (bytes32); default random */
     salt?: Hex;
+    /**
+     * sticky 2 only: rules (0 based) that switch, 2 to 4 drop rows; one of them is on at a time (the first at launch) and
+     * the switcher turns another on. Default switcher: the rule auction, where holders burn coins to pick the game.
+     */
+    switchRows?: number[];
+    switcher?: Address;
 };
 export type StickyTerms = {
     seed: bigint;
@@ -104,11 +114,47 @@ export type StickyTerms = {
 };
 /** The rows of a coin as sentences, with the template each belongs to. */
 export declare function describeRows(raw: readonly bigint[], release: number, off: number): StickyRow[];
-export declare function stickyModule(ctx: Ctx): {
+/**
+ * The table a launch would send: the templates' rows, then the hook script rows (the site's order), one release time per
+ * coin (the longer one wins); or rows + release as given. Offline; throws the problems as sentences.
+ */
+export declare function stickyTable(l: Pick<StickyLaunch, "picks" | "script" | "scriptHours" | "rows" | "release">): {
+    rows: bigint[];
+    release: number;
+};
+export type StickyTestRun = {
+    rows: bigint[];
+    release: number;
+    /** the run's numbers, as the launcher's test run shows them */
+    report: SimReport;
+    /** the run as sentences, one per line of the launcher's card */
+    text: string[];
+};
+/** A test run as sentences: the launcher's card line by line. `names` are the rows' names (rule i + 1). */
+export declare function testRunText(r: SimReport, names: string[]): string[];
+/**
+ * The launcher's test run, offline: the table on a fresh coin with random trades (the creator's first buy, three snipers
+ * in the first blocks, wallets that buy, hold and sell, bags split to fresh wallets). It runs the coin's own rule engine,
+ * checked against the contract trade by trade. The same seed gives the same run; the chain stays the truth.
+ */
+export declare function stickyTestRun(l: Pick<StickyLaunch, "picks" | "script" | "scriptHours" | "rows" | "release"> & {
+    devBuyBnb?: number;
+    seed?: number;
+    trades?: number;
+    start?: number;
+}): StickyTestRun;
+/**
+ * The sticky module. `v2` points it at the sticky 2 factory (same coins, same rules, same calls; its coins also count
+ * the creator's sold coins and can carry switch rows, see ph.sticky2).
+ */
+export declare function stickyModule(ctx: Ctx, v2?: boolean): {
     factory: `0x${string}`;
     terms: () => Promise<StickyTerms>;
     validate: (rows: bigint[], release: number, custom?: boolean) => Promise<string | null>;
+    validateSwitch: (rows: bigint[], mask: number, validator?: Address) => Promise<string | null>;
     compile: typeof compile;
+    table: typeof stickyTable;
+    testRun: typeof stickyTestRun;
     describeRows: typeof describeRows;
     prepareMetadata: (m: {
         name: string;
@@ -151,6 +197,9 @@ export declare function stickyModule(ctx: Ctx): {
         wallet?: Address;
     }) => Promise<{
         amountOut: bigint;
+        venue: Venue;
+        v3: bigint | null;
+        v2: bigint | null;
     }>;
     estimateBuy: (token: Address, bnbIn: bigint) => Promise<bigint>;
     sellApproval: (owner: Address, token: Address, amount: bigint) => Promise<TxRequest | null>;
@@ -164,6 +213,8 @@ export declare function stickyModule(ctx: Ctx): {
             salt?: Hex;
             keepBps?: number;
             minCreatorBps: number;
+            switcher?: Address;
+            switchMask?: number;
         }, value: bigint) => TxRequest;
         buy: (b: {
             token: Address;
@@ -180,6 +231,7 @@ export declare function stickyModule(ctx: Ctx): {
             deadline?: bigint;
         }) => TxRequest;
         lift: (token: Address, row: number) => TxRequest;
+        collect: (token: Address) => Promise<TxRequest>;
     };
     launch: (l: StickyLaunch, s?: SendOptions) => Promise<Sent & {
         token: Address;
@@ -194,10 +246,12 @@ export declare function stickyModule(ctx: Ctx): {
         slippageBps?: number;
         minOut?: bigint;
         deadline?: bigint;
+        venue?: Venue;
     }, s?: SendOptions) => Promise<Sent & {
         quoted: bigint;
         minOut: bigint;
         amountOut: bigint;
+        venue: Venue;
     }>;
     sell: (x: {
         token: Address;
@@ -205,11 +259,27 @@ export declare function stickyModule(ctx: Ctx): {
         slippageBps?: number;
         minOut?: bigint;
         deadline?: bigint;
+        venue?: Venue;
     }, s?: SendOptions) => Promise<Sent & {
         quoted: bigint;
         minOut: bigint;
+        venue: Venue;
     }>;
     lift: (token: Address, row: number, s?: SendOptions) => Promise<Sent>;
+    fees: (token: Address) => Promise<{
+        bnb: bigint;
+        burned: bigint;
+        toCreator: bigint;
+        creator: Address;
+        creatorBps: number;
+        keepBps: number;
+        pending: bigint;
+    }>;
+    collect: (token: Address, s?: SendOptions) => Promise<Sent & {
+        bnb: bigint;
+        toCreator: bigint;
+        burned: bigint;
+    }>;
     /** the sender's address, for callers that check before they sign */
     from: (s?: SendOptions) => Promise<`0x${string}` | undefined>;
 };

package/dist/sticky.js

@@ -1,10 +1,14 @@
 import { encodeFunctionData, parseEventLogs } from "viem";
 import { stickyFactoryAbi, stickyTokenAbi, stickyValidatorAbi } from "./abis/sticky.js";
+import { sticky2FactoryAbi, sticky2TokenAbi, sticky2ValidatorAbi } from "./abis/sticky2.js";
 import { v3PoolAbi } from "./abis/common.js";
+import { v2LockerAbi } from "./abis/v2.js";
 import { ZERO_ADDRESS } from "./addresses.js";
 import { PickhooksError, errorText, explain, toPickhooksError } from "./errors.js";
-import { ACT, LOCKED, NONE, ON, compile, decodeRow, editToRow, rowProblems, rowText, scannerOf, TEMPLATE_BY_ID, templateOf } from "./sticky-rules.js";
-import { minusBps, sendTx, senderAddress, signer } from "./tx.js";
+import { ACT, LOCKED, NONE, ON, compile, decodeRow, defaults, editToRow, rowProblems, rowText, scannerOf, TEMPLATE_BY_ID, templateOf } from "./sticky-rules.js";
+import { simulate } from "./sticky-sim.js";
+import { chainDeadline, minusBps, sendTx, senderAddress, signer } from "./tx.js";
+import { bestVenue, buildV2Buy, buildV2Sell, v2Quote } from "./v2.js";
 import { approvalFor, buildV3Buy, buildV3Sell, receivedOf, v3EstimateBuy, v3PriceBnb, v3Quote } from "./v3.js";
 const randomSalt = () => {
     const b = new Uint8Array(32);
@@ -30,15 +34,80 @@ export function describeRows(raw, release, off) {
         return { i, name, text: rowText(r, release), template: id, sticky: t?.sticky ?? false, lock: r.act === ACT.LOCK, drop: r.act === ACT.DROP, lifted: (off & (1 << i)) !== 0, raw: x };
     });
 }
-export function stickyModule(ctx) {
+/**
+ * The table a launch would send: the templates' rows, then the hook script rows (the site's order), one release time per
+ * coin (the longer one wins); or rows + release as given. Offline; throws the problems as sentences.
+ */
+export function stickyTable(l) {
+    if (!l.picks && !l.script?.length)
+        return { rows: l.rows ?? [], release: l.release ?? 0 };
+    // a template's numbers left out take its defaults
+    const picks = (l.picks ?? []).map((p) => {
+        const t = TEMPLATE_BY_ID.get(p.id);
+        if (!t)
+            throw new PickhooksError(`There is no template "${p.id}". Templates: ${[...TEMPLATE_BY_ID.keys()].join(", ")}.`, { code: "input" });
+        return { id: p.id, params: { ...defaults(t), ...p.params } };
+    });
+    const own = (l.script ?? []).map(editToRow);
+    const c = compile(picks, own);
+    const problems = [...c.problems, ...own.flatMap(rowProblems)];
+    const hours = l.scriptHours ?? 0;
+    const locks = own.some((r) => r.act === ACT.LOCK);
+    if (locks && !(hours * 3600 >= 600 && hours <= 720))
+        problems.push("Locked shares: unlock over 10 minutes to 30 days.");
+    if (problems.length)
+        throw new PickhooksError(problems.join(" "), { code: "input" });
+    return { rows: c.rows, release: locks ? Math.max(c.release, Math.round(hours * 3600)) : c.release };
+}
+const dur = (s) => s < 90 ? `${Math.round(s)} s` : s < 5400 ? `${Math.round(s / 60)} min` : s < 2 * 86_400 ? `${+(s / 3600).toFixed(1)} h` : `${+(s / 86_400).toFixed(1)} days`;
+/** A test run as sentences: the launcher's card line by line. `names` are the rows' names (rule i + 1). */
+export function testRunText(r, names) {
+    const rule = (row) => (row === LOCKED ? "still locked" : `rule ${row + 1}, ${names[row] ?? ""}`);
+    const pct = (x) => +x.toFixed(2);
+    const out = [
+        `Trades: ${r.buys.ok + r.buys.refused} buys, ${r.sells.ok + r.sells.refused} sells, ${r.sends.ok + r.sends.refused} sends in ${+r.hours.toFixed(1)} hours.`,
+        `Refused: ${r.refusals.length ? r.refusals.map((x) => `${rule(x.row)} ${x.count}x`).join(", ") : "nothing"}.`,
+        `Longest wait to sell: ${r.longestWait ? `${dur(r.longestWait)}${r.stillWaiting ? `, ${r.stillWaiting} wallets still waiting at the end` : ""}` : "nobody had to wait"}.`,
+        `Snipers: ${r.snipers.firstSellAfter !== null ? `first sold ${dur(r.snipers.firstSellAfter)} after launch` : "could not sell during the run"}.`,
+        `Split bags: ${r.splits.count ? `${r.splits.count} sent to fresh wallets, refused there again ${r.splits.refusedAfter} times` : "none"}.`,
+        `Everyone free: ${r.allFreeAfter === 0 ? "every wallet can sell everything right after the run" : r.allFreeAfter !== null ? `every wallet can sell everything ${dur(r.allFreeAfter)} after the run` : "at the latest when every lot is 30 days old"}.`,
+    ];
+    if (r.burnedPct > 0)
+        out.push(`Burned: ${pct(r.burnedPct)} % of the supply.`);
+    if (r.pot.inPct > 0)
+        out.push(`Pot: ${pct(r.pot.inPct)} % of the supply in, ${r.pot.drops} drops paid ${pct(r.pot.paidPct)} %, ${pct(r.pot.leftPct)} % left.`);
+    out.push(`A scanner's test: ${r.scanner.buy !== null
+        ? `its test buy is refused by ${rule(r.scanner.buy)}`
+        : r.scanner.sell !== null
+            ? `its sell right after the buy is refused by ${rule(r.scanner.sell)}: it can show a honeypot`
+            : "a small buy and an instant sell pass"}.`);
+    return out;
+}
+/**
+ * The launcher's test run, offline: the table on a fresh coin with random trades (the creator's first buy, three snipers
+ * in the first blocks, wallets that buy, hold and sell, bags split to fresh wallets). It runs the coin's own rule engine,
+ * checked against the contract trade by trade. The same seed gives the same run; the chain stays the truth.
+ */
+export function stickyTestRun(l) {
+    const { rows, release } = stickyTable(l);
+    const report = simulate(rows, release, { seed: l.seed ?? 7, trades: l.trades ?? 200, devBuyBnb: l.devBuyBnb ?? 0, start: l.start });
+    const names = describeRows(rows, release, 0).map((x) => x.name);
+    return { rows, release, report, text: testRunText(report, names) };
+}
+/**
+ * The sticky module. `v2` points it at the sticky 2 factory (same coins, same rules, same calls; its coins also count
+ * the creator's sold coins and can carry switch rows, see ph.sticky2).
+ */
+export function stickyModule(ctx, v2 = false) {
     const { pub, a } = ctx;
-    const FA = stickyFactoryAbi;
-    const TA = stickyTokenAbi;
+    const F = v2 ? a.sticky2Factory : a.stickyFactory;
+    const FA = (v2 ? sticky2FactoryAbi : stickyFactoryAbi);
+    const TA = (v2 ? sticky2TokenAbi : stickyTokenAbi);
     const call = (address, abi, functionName, args = []) => pub.readContract({ address, abi, functionName, args });
     /** The factory's terms now: the seed every launch pays into the V2 pair, the creator side, whether own rows are open. */
     async function terms() {
         const fns = ["seedBnb", "creatorBps", "custom", "validator", "startFdv", "platformWallet", "locker"];
-        const r = await pub.multicall({ contracts: fns.map((functionName) => ({ address: a.stickyFactory, abi: FA, functionName })), allowFailure: false });
+        const r = await pub.multicall({ contracts: fns.map((functionName) => ({ address: F, abi: FA, functionName })), allowFailure: false });
         return { seed: r[0], creatorBps: Number(r[1]), custom: r[2], validator: r[3], startFdv: r[4], platformWallet: r[5], locker: r[6] };
     }
     /** Asks the validator on chain whether a table can launch: null when it can, else the reason. */
@@ -52,6 +121,19 @@ export function stickyModule(ctx) {
             return explain(e, "The validator refused this table.").text;
         }
     }
+    const maskOf = (rowsOn) => (rowsOn ?? []).reduce((m, i) => m | (1 << i), 0);
+    /** sticky 2: asks the validator whether these rows can switch (drop rows only, 2 to 4): null when they can, else why not */
+    async function validateSwitch(rows, mask, validator) {
+        if (!v2)
+            return "Switch rows are a sticky 2 feature.";
+        try {
+            await call(validator ?? (await terms()).validator, sticky2ValidatorAbi, "switchRows", [rows, mask]);
+            return null;
+        }
+        catch (e) {
+            return explain(e, "The validator refused these switch rows.").text;
+        }
+    }
     /**
      * Stores the image and metadata on pickhooks.com and returns the metadata link (the site's /api/sticky/prepare, rate
      * limited, only while sticky rules are live on the site). A launchpad can host its own JSON and pass that link instead.
@@ -70,35 +152,31 @@ export function stickyModule(ctx) {
     /** The launch call. value = the factory's seed + the creator's first buy. */
     function buildLaunch(l, value) {
         const args = { name: l.name, symbol: l.symbol, metadata: l.metadata, rows: l.rows, release: l.release, salt: l.salt ?? randomSalt(), keepBps: l.keepBps ?? 10_000, minCreatorBps: l.minCreatorBps };
-        return { to: a.stickyFactory, value, data: encodeFunctionData({ abi: FA, functionName: "launch", args: [args] }), label: "The launch" };
+        if (!v2 && l.switchMask)
+            throw new PickhooksError("Switch rows are a sticky 2 feature.", { code: "input" });
+        // sticky 2 takes a switcher and its switch rows too: none from a plain launch
+        const full = v2 ? { ...args, switcher: l.switchMask ? (l.switcher ?? a.ruleAuction) : ZERO_ADDRESS, switchMask: l.switchMask ?? 0 } : args;
+        return { to: F, value, data: encodeFunctionData({ abi: FA, functionName: "launch", args: [full] }), label: "The launch" };
     }
     /** Builds the table from templates and hook script rows (or takes rows), checks it locally and on chain, launches, returns the coin. */
     async function launch(l, s = {}) {
-        let rows = l.rows ?? [];
-        let release = l.release ?? 0;
         const t = await terms();
         if (l.script?.length && !t.custom)
             throw new PickhooksError("The hook script is off on the factory: templates only for now.", { code: "input" });
-        if (l.picks || l.script?.length) {
-            // the site's order: the templates' rows, then the own rows; one release time per coin, the longer one wins
-            const own = (l.script ?? []).map(editToRow);
-            const c = compile(l.picks ?? [], own);
-            const problems = [...c.problems, ...own.flatMap(rowProblems)];
-            const hours = l.scriptHours ?? 0;
-            const locks = own.some((r) => r.act === ACT.LOCK);
-            if (locks && !(hours * 3600 >= 600 && hours <= 720))
-                problems.push("Locked shares: unlock over 10 minutes to 30 days.");
-            if (problems.length)
-                throw new PickhooksError(problems.join(" "), { code: "input" });
-            rows = c.rows;
-            release = locks ? Math.max(c.release, Math.round(hours * 3600)) : c.release;
-        }
+        const { rows, release } = stickyTable(l);
         const refused = await validate(rows, release, t.custom);
         if (refused)
             throw new PickhooksError(refused, { code: "Bad" });
-        const tx = buildLaunch({ name: l.name, symbol: l.symbol, metadata: l.metadata, rows, release, salt: l.salt, keepBps: l.keepBps, minCreatorBps: t.creatorBps }, t.seed + (l.devBuy ?? 0n));
+        const switchMask = maskOf(l.switchRows);
+        if (switchMask) {
+            const no = await validateSwitch(rows, switchMask, t.validator);
+            if (no)
+                throw new PickhooksError(no, { code: "Bad" });
+        }
+        const tx = buildLaunch({ name: l.name, symbol: l.symbol, metadata: l.metadata, rows, release, salt: l.salt, keepBps: l.keepBps, minCreatorBps: t.creatorBps, switcher: l.switcher, switchMask }, t.seed + (l.devBuy ?? 0n));
         const sent = await sendTx(ctx, tx, s);
-        const ev = parseEventLogs({ abi: FA, logs: sent.receipt.logs, eventName: "Launched" })[0];
+        // both factories emit the same Launched event
+        const ev = parseEventLogs({ abi: stickyFactoryAbi, logs: sent.receipt.logs.filter((x) => x.address.toLowerCase() === F.toLowerCase()), eventName: "Launched" })[0];
         if (!ev)
             throw new PickhooksError("Launched, but the coin was not found in the receipt.", { code: "receipt", hash: sent.hash });
         return { ...sent, token: ev.args.token, pool: ev.args.pool, pair: ev.args.pair, rows, release };
@@ -150,7 +228,7 @@ export function stickyModule(ctx) {
         return out;
     }
     /** How many coins the factory launched. */
-    const count = async () => Number(await call(a.stickyFactory, FA, "coinCount"));
+    const count = async () => Number(await call(F, FA, "coinCount"));
     /** Coins newest first: `limit` of them, skipping the newest `offset`. */
     async function coins(o = {}) {
         const n = await count();
@@ -160,12 +238,12 @@ export function stickyModule(ctx) {
             return [];
         const idx = Array.from({ length: end - from }, (_, i) => BigInt(end - 1 - i));
         const tokens = (await pub.multicall({
-            contracts: idx.map((i) => ({ address: a.stickyFactory, abi: FA, functionName: "coins", args: [i] })),
+            contracts: idx.map((i) => ({ address: F, abi: FA, functionName: "coins", args: [i] })),
             allowFailure: false,
         }));
         return summaries(tokens);
     }
-    const isCoin = async (token) => (await call(a.stickyFactory, FA, "isCoin", [token]).catch(() => false)) === true;
+    const isCoin = async (token) => (await call(F, FA, "isCoin", [token]).catch(() => false)) === true;
     /** One sticky coin, or null when the address is not one of the factory's coins. */
     async function coin(token) {
         if (!(await isCoin(token)))
@@ -218,11 +296,17 @@ export function stickyModule(ctx) {
      * does not pass the reason on: a refused buy 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).
      */
+    /**
+     * The better of the coin's two venues: its V3 pool and its V2 pair (every sticky coin has both at the same start price;
+     * after a dark launch the round's BNB sits in the pair, and a sell into the one sided V3 curve would get almost nothing).
+     * Terminals pick the pool by themselves; the SDK does the same here. The venue field says which one buy/sell will use.
+     */
     async function quote(q) {
-        try {
-            return { amountOut: await v3Quote(ctx, q) };
-        }
-        catch (e) {
+        const best = await bestVenue(ctx, { v3: () => v3Quote(ctx, q), v2: () => v2Quote(ctx, q) });
+        if (best.v3 !== null || best.v2 !== null)
+            return { amountOut: best.amountOut, venue: best.venue, v3: best.v3, v2: best.v2 };
+        const e = best.errors.v3 ?? best.errors.v2;
+        {
             if (q.side === "buy") {
                 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;
@@ -246,30 +330,72 @@ export function stickyModule(ctx) {
     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);
-        const sent = await sendTx(ctx, buildBuy({ token: b.token, bnbIn: b.bnbIn, minOut, recipient: address, deadline: b.deadline }), s);
-        return { ...sent, quoted: q.amountOut, minOut, amountOut: receivedOf(sent.receipt, b.token, address) };
+        const venue = b.venue ?? q.venue;
+        const quoted = (venue === "v2" ? q.v2 : q.v3) ?? q.amountOut;
+        refuse(await check({ token: b.token, side: "buy", wallet: address, amount: quoted }));
+        const minOut = b.minOut ?? minusBps(quoted, b.slippageBps ?? 100);
+        const deadline = b.deadline ?? (await chainDeadline(ctx));
+        const tx = venue === "v2" ? buildV2Buy(a, { token: b.token, bnbIn: b.bnbIn, minOut, recipient: address, deadline }) : buildBuy({ token: b.token, bnbIn: b.bnbIn, minOut, recipient: address, deadline });
+        const sent = await sendTx(ctx, tx, s);
+        return { ...sent, quoted, minOut, amountOut: receivedOf(sent.receipt, b.token, address), venue };
     }
     /** Checks the rules, approves the 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 sellApproval(address, x.token, x.amount);
+        const q = await quote({ token: x.token, side: "sell", amount: x.amount });
+        const venue = x.venue ?? q.venue;
+        const quoted = (venue === "v2" ? q.v2 : q.v3) ?? q.amountOut;
+        const ap = await approvalFor(ctx, address, x.token, x.amount, venue === "v2" ? a.v2Router : 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);
-        const sent = await sendTx(ctx, buildSell({ token: x.token, amount: x.amount, minOut, recipient: address, deadline: x.deadline }), s);
-        return { ...sent, quoted: q.amountOut, minOut };
+        const minOut = x.minOut ?? minusBps(quoted, x.slippageBps ?? 100);
+        const deadline = x.deadline ?? (await chainDeadline(ctx));
+        const tx = venue === "v2" ? buildV2Sell(a, { token: x.token, amount: x.amount, minOut, recipient: address, deadline }) : buildSell({ token: x.token, amount: x.amount, minOut, recipient: address, deadline });
+        const sent = await sendTx(ctx, tx, s);
+        return { ...sent, quoted, minOut, venue };
     }
     /** The creator lifts a row for good (a drop row cannot be lifted). */
     const buildLift = (token, row) => ({ to: token, value: 0n, data: encodeFunctionData({ abi: TA, functionName: "lift", args: [row] }), label: `Lifting rule ${row + 1}` });
+    const lockerOf = (token) => call(token, TA, "locker");
+    /** Anyone: collects the coin's trading fees from its locked position; the locker pays the creator's side to the creator. */
+    const buildCollect = async (token) => ({
+        to: await lockerOf(token),
+        value: 0n,
+        data: encodeFunctionData({ abi: v2LockerAbi, functionName: "collect", args: [token] }),
+        label: "The collect",
+    });
+    /**
+     * What collect() would book now (simulated): the BNB fees of the coin's position and the coins it burns, what of it goes
+     * to the creator (creatorBps of the fees is the creator side, keepBps of that the creator keeps, the rest buys back and
+     * burns $hooks), and BNB the locker holds for the creator because a payout bounced (withdrawPending() takes it).
+     */
+    async function fees(token) {
+        const locker = await lockerOf(token);
+        const pos = await call(locker, v2LockerAbi, "positions", [token]);
+        const [sim, pending] = await Promise.all([
+            pub.simulateContract({ address: locker, abi: v2LockerAbi, functionName: "collect", args: [token] }).then((r) => r.result),
+            call(locker, v2LockerAbi, "pending", [pos[2]]),
+        ]);
+        // the locker's own split
+        const side = (sim[0] * BigInt(pos[3])) / 10000n;
+        const toCreator = ((side - (side * BigInt(pos[4])) / 10000n) * BigInt(pos[5])) / 10000n;
+        return { bnb: sim[0], burned: sim[1], toCreator, creator: pos[2], creatorBps: Number(pos[3]), keepBps: Number(pos[5]), pending };
+    }
+    /** Collects the coin's fees; returns what the locker booked (its Collected event). */
+    async function collect(token, s = {}) {
+        const sent = await sendTx(ctx, await buildCollect(token), s);
+        const ev = parseEventLogs({ abi: v2LockerAbi, logs: sent.receipt.logs, eventName: "Collected" })[0];
+        return { ...sent, bnb: ev?.args.bnb ?? 0n, toCreator: ev?.args.toCreator ?? 0n, burned: ev?.args.burned ?? 0n };
+    }
     return {
-        factory: a.stickyFactory,
+        factory: F,
         terms,
         validate,
+        validateSwitch,
         compile,
+        table: stickyTable,
+        testRun: stickyTestRun,
         describeRows,
         prepareMetadata,
         count,
@@ -281,11 +407,13 @@ export function stickyModule(ctx) {
         quote,
         estimateBuy,
         sellApproval,
-        build: { launch: buildLaunch, buy: buildBuy, sell: buildSell, lift: buildLift },
+        build: { launch: buildLaunch, buy: buildBuy, sell: buildSell, lift: buildLift, collect: buildCollect },
         launch,
         buy,
         sell,
         lift: (token, row, s = {}) => sendTx(ctx, buildLift(token, row), s),
+        fees,
+        collect,
         /** the sender's address, for callers that check before they sign */
         from: (s = {}) => senderAddress(ctx, s.wallet),
     };

package/dist/tlock.d.ts

@@ -0,0 +1,67 @@
+import type { Hex } from "viem";
+export type Net = {
+    chainHash: string;
+    publicKey: string;
+    genesis: number;
+    period: number;
+    dst: string;
+    urls: string[];
+};
+export type Sealed = {
+    u: Hex;
+    v: Hex;
+    w: Hex;
+    round: number;
+    sigma: Hex;
+};
+export declare const QUICKNET: Net;
+declare const G2: import("@noble/curves/abstract/weierstrass").ProjConstructor<import("@noble/curves/abstract/tower").Fp2>;
+type G2P = InstanceType<typeof G2>;
+/** r = (keccak(TAG3 || 0x01 || sigma || M) * 2^256 + keccak(TAG3 || 0x02 || sigma || M)) mod q, never 0. */
+export declare function h3(sigma: Uint8Array, m: Uint8Array): bigint;
+/** keccak(TAG4 || sigma). */
+export declare function h4(sigma: Uint8Array): Uint8Array;
+/** First second at which drand publishes the round. */
+export declare function roundTime(round: number | bigint, net?: Net): number;
+/** First round published at or after `unixSeconds`. */
+export declare function roundAt(unixSeconds: number, net?: Net): number;
+/** The round's identity point: hash_to_G1(sha256(round as 8 bytes big endian)), as drand quicknet signs it. */
+export declare function roundPoint(round: number | bigint, net?: Net): import("@noble/curves/abstract/weierstrass").ProjPointType<bigint>;
+/** True when `sigHex` is drand's signature on `round` under the network's key. */
+export declare function verifyRoundSig(round: number | bigint, sigHex: string, net?: Net): boolean;
+/** G2 point to the 256 byte EIP-2537 encoding: x.c0, x.c1, y.c0, y.c1, each 64 bytes (16 zero bytes + 48). */
+export declare function g2ToEip(point: G2P): Hex;
+export declare function g2FromEip(h: string): G2P;
+/** The 32 byte message of a dark launch bid: the bidder (20 bytes), the step (1 byte), 11 zero bytes. */
+export declare function darkMessage(bidder: string, step: number): Hex;
+export declare function parseDarkMessage(m: string): {
+    bidder: Hex;
+    step: number;
+    clean: boolean;
+};
+/**
+ * Encrypts 32 bytes to a drand round. Returns hex ready for the contracts: u (256 bytes), v and w (32 each).
+ * `opts.sigma` and `opts.publicKey` exist for tests only.
+ */
+export declare function encrypt(round: number | bigint, message: string | Uint8Array, opts?: {
+    net?: Net;
+    sigma?: string | Uint8Array;
+    publicKey?: string;
+}): Sealed;
+/** Opens a ciphertext with drand's signature on its round: { sigma, message }, or null when it does not open. */
+export declare function decrypt(c: {
+    u: string;
+    v: string;
+    w: string;
+}, sigHex: string): {
+    sigma: Hex;
+    message: Hex;
+} | null;
+/** The contract's own check, in JS: U == H3(sigma, M) * G2 and W == M xor H4(sigma). */
+export declare function opens(c: {
+    u: string;
+    w: string;
+}, sigma: string | Uint8Array, message: string | Uint8Array): boolean;
+/** drand's signature on `round` (hex, 48 bytes), checked against the network's key. Null while the round is not out. */
+export declare function fetchRoundSig(round: number | bigint, net?: Net, fetcher?: typeof fetch): Promise<string | null>;
+export {};