@pickhooks/sdk 0.2.0 → 0.5.0

package/dist/sticky.d.ts

@@ -1,6 +1,10 @@
 import { type Address, type Hex } from "viem";
-import { type EditRow, type Pick, compile } from "./sticky-rules.js";
+import { type ModeName } from "./addresses.js";
+import { type ModeSettings } from "./modes-catalog.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
@@ -52,6 +56,13 @@ export type StickyCoin = {
     /** BNB per coin at the V3 pool's price, and the market cap in BNB */
     priceBnb: number;
     mcapBnb: number;
+    /** sticky 3: the coin's mode (its name, or "other" for a mode the SDK does not know), its share of buys and the game pot */
+    mode?: {
+        name: ModeName | "other" | null;
+        address: Address;
+        gameBps: number;
+        gamePot: bigint;
+    };
 };
 export type StickyLot = {
     amount: bigint;
@@ -75,8 +86,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 +105,15 @@ 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;
+    /** sticky 3 only: the coin's mode (fixed for good) and its settings within the mode's bounds (defaults when left out) */
+    mode?: ModeName;
+    modeSettings?: ModeSettings;
 };
 export type StickyTerms = {
     seed: bigint;
@@ -104,11 +126,50 @@ 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). `3` points it at sticky 3: the same again, plus a
+ * mode per coin (launch with `mode` and `modeSettings`; the game itself is ph.modes); a sticky 3 coin leaves its lot
+ * views to the lens.
+ */
+export declare function stickyModule(ctx: Ctx, version?: boolean | 3): {
     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>;
+    validateMode: (mode: ModeName, settings: ModeSettings | undefined, rows: bigint[], validator?: Address, creator?: Address) => Promise<string | null>;
     compile: typeof compile;
+    table: typeof stickyTable;
+    testRun: typeof stickyTestRun;
     describeRows: typeof describeRows;
     prepareMetadata: (m: {
         name: string;
@@ -136,6 +197,7 @@ export declare function stickyModule(ctx: Ctx): {
         balance: bigint;
         sellable: bigint;
         lots: StickyLot[];
+        held?: bigint;
     }>;
     check: (c: {
         token: Address;
@@ -151,8 +213,12 @@ 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>;
+    buyTakeBps: (token: Address) => Promise<number>;
     sellApproval: (owner: Address, token: Address, amount: bigint) => Promise<TxRequest | null>;
     build: {
         launch: (l: {
@@ -164,6 +230,10 @@ export declare function stickyModule(ctx: Ctx): {
             salt?: Hex;
             keepBps?: number;
             minCreatorBps: number;
+            switcher?: Address;
+            switchMask?: number;
+            mode?: ModeName;
+            modeSettings?: ModeSettings;
         }, value: bigint) => TxRequest;
         buy: (b: {
             token: Address;
@@ -180,6 +250,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 +265,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 +278,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,11 +1,30 @@
 import { encodeFunctionData, parseEventLogs } from "viem";
 import { stickyFactoryAbi, stickyTokenAbi, stickyValidatorAbi } from "./abis/sticky.js";
+import { sticky2FactoryAbi, sticky2TokenAbi, sticky2ValidatorAbi } from "./abis/sticky2.js";
+import { sticky3FactoryAbi, sticky3LensAbi, sticky3TokenAbi, sticky3ValidatorAbi } from "./abis/sticky3.js";
+import { MODE_NAMES } from "./addresses.js";
+import { encodeModeData } from "./modes-catalog.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 sticky3ModeQuoteAbi = [
+    {
+        type: "function",
+        name: "quote",
+        stateMutability: "view",
+        inputs: [
+            { name: "creator", type: "address" },
+            { name: "data", type: "bytes" },
+        ],
+        outputs: [{ name: "gameBps", type: "uint16" }],
+    },
+];
 const randomSalt = () => {
     const b = new Uint8Array(32);
     globalThis.crypto.getRandomValues(b);
@@ -30,15 +49,85 @@ 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). `3` points it at sticky 3: the same again, plus a
+ * mode per coin (launch with `mode` and `modeSettings`; the game itself is ph.modes); a sticky 3 coin leaves its lot
+ * views to the lens.
+ */
+export function stickyModule(ctx, version = false) {
     const { pub, a } = ctx;
-    const FA = stickyFactoryAbi;
-    const TA = stickyTokenAbi;
+    const v3 = version === 3;
+    const v2 = version === true || v3; // sticky 3 has everything sticky 2 has
+    const F = v3 ? a.sticky3Factory : v2 ? a.sticky2Factory : a.stickyFactory;
+    const FA = (v3 ? sticky3FactoryAbi : v2 ? sticky2FactoryAbi : stickyFactoryAbi);
+    const TA = (v3 ? sticky3TokenAbi : v2 ? sticky2TokenAbi : stickyTokenAbi);
+    const modeName = (m) => m.toLowerCase() === ZERO_ADDRESS ? null : (MODE_NAMES.find((n) => a.modes[n].toLowerCase() === m.toLowerCase()) ?? "other");
     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 +141,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, (v3 ? sticky3ValidatorAbi : 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 +172,65 @@ 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 full2 = v2 ? { ...args, switcher: l.switchMask ? (l.switcher ?? a.ruleAuction) : ZERO_ADDRESS, switchMask: l.switchMask ?? 0 } : args;
+        if (!v3 && l.mode)
+            throw new PickhooksError("Modes are a sticky 3 feature.", { code: "input" });
+        const modeAddr = l.mode ? a.modes[l.mode] : ZERO_ADDRESS;
+        if (l.mode && modeAddr.toLowerCase() === ZERO_ADDRESS)
+            throw new PickhooksError(`The mode ${l.mode} is not deployed yet.`, { code: "input" });
+        const full = v3 ? { ...full2, mode: modeAddr, modeData: l.mode ? encodeModeData(l.mode, l.modeSettings) : "0x" } : full2;
+        return { to: F, value, data: encodeFunctionData({ abi: FA, functionName: "launch", args: [full] }), label: "The launch" };
+    }
+    /**
+     * sticky 3: asks the mode for its share of buys with these settings (it refuses settings out of bounds) and the validator
+     * whether that share fits next to the rows' burns and pots (10 % of a buy at most). null when the launch can go.
+     */
+    async function validateMode(mode, settings, rows, validator, creator) {
+        if (!v3)
+            return "Modes are a sticky 3 feature.";
+        const m = a.modes[mode];
+        if (m.toLowerCase() === ZERO_ADDRESS)
+            return `The mode ${mode} is not deployed yet.`;
+        try {
+            const listed = await call(F, FA, "modes", [m]);
+            if (!listed)
+                return `The mode ${mode} is not open for launches yet.`;
+            const from = creator ?? (await senderAddress(ctx)) ?? ZERO_ADDRESS;
+            const bps = await call(m, sticky3ModeQuoteAbi, "quote", [from, encodeModeData(mode, settings)]);
+            await call(validator ?? (await terms()).validator, sticky3ValidatorAbi, "game", [rows, bps]);
+            return null;
+        }
+        catch (e) {
+            return explain(e, "The mode refused these settings.").text;
+        }
     }
     /** 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" });
+        }
+        if (l.mode) {
+            const no = await validateMode(l.mode, l.modeSettings, rows, 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, mode: l.mode, modeSettings: l.modeSettings }, 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 };
@@ -114,6 +246,16 @@ export function stickyModule(ctx) {
             contracts: pools.map((p) => ({ address: (p ?? a.wbnb), abi: v3PoolAbi, functionName: "slot0" })),
             allowFailure: true,
         });
+        const modeRes = v3
+            ? await pub.multicall({
+                contracts: tokens.flatMap((t) => [
+                    { address: t, abi: TA, functionName: "mode" },
+                    { address: t, abi: TA, functionName: "gameBps" },
+                    { address: t, abi: TA, functionName: "gamePot" },
+                ]),
+                allowFailure: true,
+            })
+            : [];
         const out = [];
         tokens.forEach((token, i) => {
             const g = (k) => res[i * per + k];
@@ -145,12 +287,22 @@ export function stickyModule(ctx) {
                 totalSupply: supply,
                 priceBnb,
                 mcapBnb: priceBnb * (Number(supply) / 1e18),
+                ...(v3 && modeRes[i * 3]?.status === "success"
+                    ? {
+                        mode: {
+                            name: modeName(modeRes[i * 3].result),
+                            address: modeRes[i * 3].result,
+                            gameBps: Number(modeRes[i * 3 + 1].result ?? 0),
+                            gamePot: modeRes[i * 3 + 2].result ?? 0n,
+                        },
+                    }
+                    : {}),
             });
         });
         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 +312,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)))
@@ -174,6 +326,20 @@ export function stickyModule(ctx) {
     }
     /** A wallet's lots (amount, locked part, since, marks), its balance and what it can sell now. */
     async function wallet(token, who) {
+        if (v3) {
+            const [bal, sellable, lots, held] = await Promise.all([
+                call(token, TA, "balanceOf", [who]),
+                call(a.sticky3Lens, sticky3LensAbi, "sellable", [token, who]),
+                call(a.sticky3Lens, sticky3LensAbi, "lotsOf", [token, who]),
+                call(token, TA, "heldOf", [who]),
+            ]);
+            return {
+                balance: bal,
+                sellable,
+                lots: lots.amount.map((x, i) => ({ amount: x, locked: lots.locked[i], since: Number(lots.since[i]), flags: Number(lots.flags[i]), open: lots.open[i] })),
+                held: held[0],
+            };
+        }
         const r = await pub.multicall({
             contracts: [
                 { address: token, abi: TA, functionName: "balanceOf", args: [who] },
@@ -218,11 +384,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;
@@ -242,34 +414,97 @@ export function stickyModule(ctx) {
         if (!c.ok)
             throw new PickhooksError(c.text, { code: "Blocked", args: [c.row === "locked" ? LOCKED : c.row] });
     };
+    /**
+     * The share of a buy the coin keeps, basis points: its burn and pot rows on buys that are not lifted, and a sticky 3
+     * coin's game share (at most 10 %). The V2 router measures what arrives in the wallet, after the coin took its share,
+     * so a V2 buy's minimum leaves it out; the V3 router measures what the pool sends, before it.
+     */
+    async function buyTakeBps(token) {
+        const [raw, , off] = await call(token, TA, "script");
+        let take = 0;
+        raw.forEach((x, i) => {
+            if ((Number(off) >> i) & 1)
+                return;
+            const r = decodeRow(x);
+            if (r.on & ON.BUY && (r.act === ACT.BURN || r.act === ACT.POT))
+                take += r.arg;
+        });
+        if (v3)
+            take += Number(await call(token, TA, "gameBps").catch(() => 0));
+        return Math.min(take, 1000);
+    }
     /** Quotes, checks the coin's rules for this wallet, and buys. 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);
-        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 arrives = venue === "v2" ? minusBps(quoted, await buyTakeBps(b.token)) : quoted;
+        const minOut = b.minOut ?? minusBps(arrives, 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,
+        validateMode,
         compile,
+        table: stickyTable,
+        testRun: stickyTestRun,
         describeRows,
         prepareMetadata,
         count,
@@ -280,12 +515,15 @@ export function stickyModule(ctx) {
         check,
         quote,
         estimateBuy,
+        buyTakeBps,
         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),
     };