@pickhooks/sdk 0.2.0 → 0.5.0

package/dist/modes.js

@@ -0,0 +1,86 @@
+import { encodeFunctionData, } from "viem";
+import { comboModeAbi, forwardModeAbi, sticky3FactoryAbi, sticky3TokenAbi, } from "./abis/sticky3.js";
+import { MODE_NAMES, ZERO_ADDRESS } from "./addresses.js";
+import { PickhooksError } from "./errors.js";
+import { MODE_LIST, MODES, encodeModeData, modeBps } from "./modes-catalog.js";
+import { sendTx, } from "./tx.js";
+export function modesModule(ctx) {
+    const { pub, a } = ctx;
+    const call = (address, abi, functionName, args = []) => pub.readContract({ address, abi: abi, functionName, args });
+    const tx = (to, abi, functionName, args, label, value = 0n) => ({
+        to,
+        value,
+        data: encodeFunctionData({ abi: abi, functionName, args }),
+        label,
+    });
+    const playTx = (coin, data, label) => tx(coin, sticky3TokenAbi, "play", [data], label);
+    const pokeTx = (coin, data, label) => tx(coin, sticky3TokenAbi, "poke", [data], label);
+    const send = (t, s = {}) => sendTx(ctx, t, s);
+    const now = async () => Number((await pub.getBlock()).timestamp);
+    const modeAddr = (n) => {
+        const m = a.modes[n];
+        if (m.toLowerCase() === ZERO_ADDRESS)
+            throw new PickhooksError(`The mode ${MODES[n].title} is not deployed yet.`, { code: "input" });
+        return m;
+    };
+    /** The coin's mode: its name (null: no mode, "other": a mode the SDK does not know), address, share of buys, game pot. */
+    async function of(coin) {
+        const [m, bps, pot] = await Promise.all([
+            call(coin, sticky3TokenAbi, "mode"),
+            call(coin, sticky3TokenAbi, "gameBps"),
+            call(coin, sticky3TokenAbi, "gamePot"),
+        ]);
+        const name = m.toLowerCase() === ZERO_ADDRESS ? null : (MODE_NAMES.find((n) => a.modes[n].toLowerCase() === m.toLowerCase()) ?? "other");
+        return { name, address: m, gameBps: Number(bps), gamePot: pot, info: name && name !== "other" ? MODES[name] : null };
+    }
+    /** A holder's custody in a coin: coins, of them DEV, until, since, the shadow address they sit at, and whether anyone may release it now. */
+    async function custody(coin, who) {
+        const [h, shadow, t] = await Promise.all([
+            call(coin, sticky3TokenAbi, "heldOf", [who]),
+            call(coin, sticky3TokenAbi, "shadow", [who]),
+            now(),
+        ]);
+        return { amount: h[0], dev: h[1], until: Number(h[2]), since: Number(h[3]), shadow, releasable: h[0] > 0n && t >= Number(h[2]) };
+    }
+    const buildRelease = (coin, who) => tx(coin, sticky3TokenAbi, "releaseHeld", [who], "Releasing the custody");
+    /** Is the mode open for launches on the factory now (listed). */
+    const listed = async (n) => a.modes[n].toLowerCase() !== ZERO_ADDRESS && (await call(a.sticky3Factory, sticky3FactoryAbi, "modes", [a.modes[n]]).catch(() => false));
+    // ---------------------------------------------------------------- the modes that live on trades
+    const combo = {
+        async state(coin) {
+            const g = await call(modeAddr("combo"), comboModeAbi, "games", [coin]);
+            const c = Number(g[0]);
+            const next = Number(await call(modeAddr("combo"), comboModeAbi, "nextAt", [BigInt(c)]));
+            const share = Number(await call(modeAddr("combo"), comboModeAbi, "shareAt", [BigInt(next)]));
+            return { combo: c, best: Number(g[1]), hits: Number(g[2]), bps: Number(g[3]), minPpm: Number(g[4]), breaker: g[5], brokeAt: Number(g[6]), next, nextSharePct: share / 100 };
+        },
+    };
+    const forward = {
+        async state(coin) {
+            const g = await call(modeAddr("forward"), forwardModeAbi, "games", [coin]);
+            return { last: g[0], lastGot: g[1], bps: Number(g[2]), minPpm: Number(g[3]), forwards: Number(g[4]) };
+        },
+    };
+    return {
+        /** the modes: line, how they play, share of buys and bounds, actions (offline) */
+        catalog: MODES,
+        list: MODE_LIST,
+        info: (n) => MODES[n],
+        /** a mode's settings encoded for the launch (zeros: defaults) */
+        encode: encodeModeData,
+        /** the share of buys a mode takes with these settings */
+        bps: modeBps,
+        /** is the mode open for launches on the factory now */
+        listed,
+        of,
+        custody,
+        build: { release: buildRelease, play: playTx, poke: pokeTx },
+        /** anyone: a holder's custody back to the wallet once its time is up */
+        release: (coin, who, s) => send(buildRelease(coin, who), s),
+        /** a raw play or poke (data: abi.encode(action, ...)) for modes the SDK does not know */
+        play: (coin, data, s) => send(playTx(coin, data, "The play"), s),
+        poke: (coin, data, s) => send(pokeTx(coin, data, "The poke"), s),
+        combo,
+        forward,
+    };
+}

package/dist/simulate.d.ts

@@ -0,0 +1,75 @@
+import { type Address, type Hex } from "viem";
+import { type Ctx, type TxRequest } from "./tx.js";
+import { type Venue } from "./v2.js";
+export type SimResult = {
+    ok: boolean;
+    /** why it would fail, as a sentence (the rule, the mode, PancakeSwap) */
+    refused?: {
+        code: string;
+        text: string;
+    };
+    /** what reaches the wallet: coins on a buy, BNB (wei) on a sell, 0 on a send or a play */
+    out: bigint;
+    /** coins that burn (takes of the rows, the mode's burns) */
+    burned: bigint;
+    /** coins into the coin's pots (the rows' pot and the game pot together) */
+    toPots: bigint;
+    /** the game pot before and after (sticky 3) */
+    gamePot?: {
+        before: bigint;
+        after: bigint;
+    };
+    /** coins the pots pay to this wallet (a drop row, the mode's bonus) */
+    bonus: bigint;
+    /** coins that go into this wallet's custody */
+    intoCustody: bigint;
+    /** coins that leave this wallet's custody */
+    outOfCustody: bigint;
+    /** pot payouts to other wallets (pay it forward pays the last buyer) */
+    paidOthers: {
+        to: Address;
+        amount: bigint;
+    }[];
+    /** the mode's events and the coin's custody events, as sentences */
+    events: string[];
+    gas: bigint;
+    venue?: Venue;
+};
+/** The shadow address a sticky 3 coin keeps `who`'s custody at. */
+export declare function shadowOf(who: Address): Address;
+/** A mode event or a coin event as a sentence (null for events nobody needs to read). */
+export declare function eventText(name: string, args: Record<string, unknown>): string | null;
+export declare function simulateModule(ctx: Ctx): {
+    buy: (b: {
+        token: Address;
+        wallet: Address;
+        bnbIn: bigint;
+        venue?: Venue;
+    }) => Promise<SimResult>;
+    sell: (x: {
+        token: Address;
+        wallet: Address;
+        amount: bigint;
+        venue?: Venue;
+    }) => Promise<SimResult>;
+    send: (x: {
+        token: Address;
+        wallet: Address;
+        to: Address;
+        amount: bigint;
+    }) => Promise<SimResult>;
+    play: (x: {
+        token: Address;
+        wallet: Address;
+        data: Hex;
+        poke?: boolean;
+    }) => Promise<SimResult>;
+    tx: (x: {
+        token: Address;
+        wallet: Address;
+        tx: TxRequest;
+    }) => Promise<SimResult>;
+    shadowOf: typeof shadowOf;
+    eventText: typeof eventText;
+};
+export type SimulateModule = ReturnType<typeof simulateModule>;

package/dist/simulate.js

@@ -0,0 +1,225 @@
+import { concat, decodeEventLog, encodeFunctionData, erc20Abi, getAddress, keccak256, maxUint256, slice, toHex } from "viem";
+import { comboModeAbi, forwardModeAbi, sticky3TokenAbi, } from "./abis/sticky3.js";
+import { stickyTokenAbi } from "./abis/sticky.js";
+import { ZERO_ADDRESS } from "./addresses.js";
+import { errorText, explain } from "./errors.js";
+import { describeRows } from "./sticky.js";
+import { v3EstimateBuy } from "./v3.js";
+import {} from "./tx.js";
+import { buildV2Buy, buildV2Sell } from "./v2.js";
+import { buildV3Buy, buildV3Sell } from "./v3.js";
+/**
+ * ph.simulate: every buy, sell, send or play tried first against the chain as it is now (eth_simulateV1, nothing is
+ * sent). What comes back is what the coin would do: the coins or BNB that arrive, what burns, what goes into the pots,
+ * what a pot pays out (a drop row, the mode's bonus), what goes into custody, the mode's own events as sentences, or the
+ * rule, the mode or PancakeSwap reason that would stop it. For agents: trade safely. For terminals: "this is a rule, not
+ * a honeypot", in black and white.
+ */
+const DEAD = "0x000000000000000000000000000000000000dEaD";
+const FAR = 2n ** 40n;
+const MODE_ABIS = [
+    comboModeAbi,
+    forwardModeAbi,
+];
+const short = (x) => `${x.slice(0, 6)}…${x.slice(-4)}`;
+const coins = (x) => {
+    const n = Number(x) / 1e18;
+    return n >= 1e6 ? `${+(n / 1e6).toFixed(2)}M` : n >= 1e3 ? `${+(n / 1e3).toFixed(1)}k` : `${+n.toFixed(2)}`;
+};
+/** The shadow address a sticky 3 coin keeps `who`'s custody at. */
+export function shadowOf(who) {
+    return getAddress(slice(keccak256(concat([toHex("pickhooks.custody"), who])), 12));
+}
+/** A mode event or a coin event as a sentence (null for events nobody needs to read). */
+export function eventText(name, args) {
+    const a = (k) => args[k];
+    switch (name) {
+        case "ModeSkipped":
+            return "The mode failed on this trade: the trade goes through without its effect.";
+        case "Held":
+            return `${short(a("who"))} has ${coins(a("amount"))} coins in custody until ${new Date(Number(a("until")) * 1000).toISOString().slice(0, 16).replace("T", " ")} UTC.`;
+        case "ComboUp":
+            return `The combo is at ${a("combo")}.`;
+        case "ComboHit":
+            return `Combo ${a("combo")}: this buy wins ${coins(a("paid"))} coins from the pot.`;
+        case "ComboBroken":
+            return `This sell breaks the combo at ${a("combo")}.`;
+        case "Forwarded":
+            return a("amount") > 0n ? `${coins(a("amount"))} coins go to the last buyer ${short(a("paid"))}; ${coins(a("burned"))} burn.` : `${coins(a("burned"))} coins burn (nobody to pay forward).`;
+        default:
+            return null;
+    }
+}
+export function simulateModule(ctx) {
+    const { pub, a } = ctx;
+    async function run(o) {
+        const { token, wallet } = o;
+        const v3 = await pub
+            .readContract({ address: token, abi: sticky3TokenAbi, functionName: "gamePot" })
+            .then(() => true)
+            .catch(() => false);
+        const potCall = { to: token, data: encodeFunctionData({ abi: sticky3TokenAbi, functionName: "gamePot" }) };
+        const bal = await pub.getBalance({ address: wallet });
+        const need = (o.bnb ?? 0n) + 10n ** 18n;
+        const calls = [...(v3 ? [potCall] : []), ...o.calls.map((c) => ({ to: c.to, data: c.data, value: c.value })), ...(v3 ? [potCall] : [])];
+        let r;
+        try {
+            r = (await pub.simulateCalls({ account: wallet, calls, stateOverrides: bal < need ? [{ address: wallet, balance: need }] : undefined }));
+        }
+        catch (e) {
+            return { ok: false, refused: explain(e, "The trade would fail."), out: 0n, burned: 0n, toPots: 0n, bonus: 0n, intoCustody: 0n, outOfCustody: 0n, paidOthers: [], events: [], gas: 0n };
+        }
+        const results = r.results;
+        const mine = v3 ? results.slice(1, -1) : results;
+        const fail = mine.find((x) => x.status !== "success");
+        const gas = mine.reduce((s, x) => s + (x.gasUsed ?? 0n), 0n);
+        if (fail) {
+            let e = explain(fail.error ?? Object.assign(new Error("reverted"), { data: fail.data }), "The trade would fail.");
+            // PancakeSwap's routers pass a refused transfer on as STF or TF: ask the coin which rule it was
+            if (o.check && !/^(Blocked|Bad|LowGas|Busy|BadOrder|NoMode)$/.test(e.code))
+                e = (await whyNot(token, o.check)) ?? e;
+            return { ok: false, refused: { code: e.code, text: e.text }, out: 0n, burned: 0n, toPots: 0n, bonus: 0n, intoCustody: 0n, outOfCustody: 0n, paidOthers: [], events: [], gas };
+        }
+        const logs = mine.flatMap((x) => x.logs ?? []);
+        const res = { ok: true, out: 0n, burned: 0n, toPots: 0n, bonus: 0n, intoCustody: 0n, outOfCustody: 0n, paidOthers: [], events: [], gas };
+        if (v3) {
+            const before = BigInt(results[0].data);
+            const after = BigInt(results[results.length - 1].data);
+            res.gamePot = { before, after };
+        }
+        const pools = o.pools.map((p) => p.toLowerCase());
+        const me = wallet.toLowerCase();
+        const sh = shadowOf(wallet).toLowerCase();
+        const coin = token.toLowerCase();
+        for (const l of logs) {
+            const at = l.address.toLowerCase();
+            if (at === coin) {
+                let ev;
+                try {
+                    ev = decodeEventLog({ abi: sticky3TokenAbi, data: l.data, topics: l.topics });
+                }
+                catch {
+                    try {
+                        ev = decodeEventLog({ abi: stickyTokenAbi, data: l.data, topics: l.topics });
+                    }
+                    catch {
+                        continue;
+                    }
+                }
+                if (ev.eventName === "Transfer") {
+                    const from = String(ev.args.from).toLowerCase();
+                    const to = String(ev.args.to).toLowerCase();
+                    const v = ev.args.value;
+                    if (to === DEAD.toLowerCase())
+                        res.burned += v;
+                    else if (to === coin && from !== coin)
+                        res.toPots += v;
+                    else if (from === coin && to === me)
+                        res.bonus += v;
+                    else if (from === coin && to === sh)
+                        res.intoCustody += v;
+                    else if (from === coin)
+                        res.paidOthers.push({ to: getAddress(to), amount: v });
+                    else if (to === sh)
+                        res.intoCustody += v;
+                    else if (from === sh)
+                        res.outOfCustody += v;
+                    if (to === me && pools.includes(from))
+                        res.out += v;
+                    continue;
+                }
+                const t = eventText(ev.eventName, ev.args);
+                if (t)
+                    res.events.push(t);
+                continue;
+            }
+            for (const abi of MODE_ABIS) {
+                try {
+                    const ev = decodeEventLog({ abi, data: l.data, topics: l.topics });
+                    const t = eventText(ev.eventName, ev.args);
+                    if (t)
+                        res.events.push(t);
+                    break;
+                }
+                catch {
+                    /* another mode's event */
+                }
+            }
+        }
+        return res;
+    }
+    /** The coin's own answer for a trade (check()), as a sentence, or null when it would let it through. */
+    async function whyNot(token, c) {
+        try {
+            const amount = typeof c.amount === "function" ? await c.amount() : c.amount;
+            const r = Number(await pub.readContract({ address: token, abi: stickyTokenAbi, functionName: "check", args: [c.kind, c.from, c.to, amount] }));
+            if (r === 255)
+                return null;
+            if (r === 254)
+                return { code: "Blocked", text: errorText("Blocked", [254]) };
+            const [raw, release, off] = (await pub.readContract({ address: token, abi: stickyTokenAbi, functionName: "script" }));
+            const row = describeRows(raw, Number(release), Number(off))[r];
+            return { code: "Blocked", text: `Refused by rule ${r + 1}${row ? `: ${row.name}. ${row.text}` : "."}` };
+        }
+        catch {
+            return null;
+        }
+    }
+    const poolsOf = async (token) => {
+        const [p, p2] = await Promise.all([
+            pub.readContract({ address: token, abi: stickyTokenAbi, functionName: "pool" }).catch(() => ZERO_ADDRESS),
+            pub.readContract({ address: token, abi: stickyTokenAbi, functionName: "pool2" }).catch(() => ZERO_ADDRESS),
+        ]);
+        return [p, p2];
+    };
+    /** A buy of `bnbIn` (wei) by `wallet` through PancakeSwap (V3 by default, `venue` "v2" for the pair). */
+    async function buy(b) {
+        const venue = b.venue ?? "v3";
+        const t = venue === "v2" ? buildV2Buy(a, { token: b.token, bnbIn: b.bnbIn, minOut: 0n, recipient: b.wallet, deadline: FAR }) : buildV3Buy(a, { token: b.token, bnbIn: b.bnbIn, minOut: 0n, recipient: b.wallet, deadline: FAR });
+        const pools = await poolsOf(b.token);
+        const check = { kind: 1, from: ZERO_ADDRESS, to: b.wallet, amount: () => v3EstimateBuy(ctx, pools[0], b.token, b.bnbIn) };
+        return { ...(await run({ token: b.token, wallet: b.wallet, calls: [t], bnb: b.bnbIn, pools, check })), venue };
+    }
+    /** A sell of `amount` coins by `wallet` for BNB (the approval to the router included in the run). */
+    async function sell(x) {
+        const venue = x.venue ?? "v3";
+        const router = venue === "v2" ? a.v2Router : a.v3Router;
+        const approve = { to: x.token, value: 0n, data: encodeFunctionData({ abi: erc20Abi, functionName: "approve", args: [router, maxUint256] }) };
+        const t = venue === "v2" ? buildV2Sell(a, { token: x.token, amount: x.amount, minOut: 0n, recipient: x.wallet, deadline: FAR }) : buildV3Sell(a, { token: x.token, amount: x.amount, minOut: 0n, recipient: x.wallet, deadline: FAR });
+        const before = await pub.getBalance({ address: x.wallet });
+        const pools = await poolsOf(x.token);
+        const r = await run({ token: x.token, wallet: x.wallet, calls: [approve, t], pools, check: { kind: 2, from: x.wallet, to: pools[0], amount: x.amount } });
+        // the BNB out: the router unwraps to the wallet (native BNB, no Transfer log); ask the chain for the balance after
+        if (r.ok) {
+            const sim = await pub
+                .simulateCalls({
+                account: x.wallet,
+                calls: [{ to: approve.to, data: approve.data }, { to: t.to, data: t.data }, { to: "0xcA11bde05977b3631167028862bE2a173976CA11", data: encodeFunctionData({ abi: [{ type: "function", name: "getEthBalance", stateMutability: "view", inputs: [{ name: "a", type: "address" }], outputs: [{ type: "uint256" }] }], functionName: "getEthBalance", args: [x.wallet] }) }],
+            })
+                .catch(() => null);
+            const last = sim?.results[2];
+            if (last?.status === "success") {
+                const after = BigInt(last.data);
+                const spent = sim.results[0].gasUsed + sim.results[1].gasUsed;
+                r.out = after > before ? after - before : 0n;
+                void spent; // eth_simulateV1 runs without a gas price: the balance moves by the trade only
+            }
+        }
+        return { ...r, venue };
+    }
+    /** A send of `amount` coins from `wallet` to `to` (a forward of a router, too). */
+    async function send(x) {
+        const t = { to: x.token, value: 0n, data: encodeFunctionData({ abi: erc20Abi, functionName: "transfer", args: [x.to, x.amount] }) };
+        return run({ token: x.token, wallet: x.wallet, calls: [t], pools: await poolsOf(x.token), check: { kind: 4, from: x.wallet, to: x.to, amount: x.amount } });
+    }
+    /** A play (abi.encode(action, ...)) or a poke by `wallet`: what the mode would do with it. */
+    async function play(x) {
+        const t = { to: x.token, value: 0n, data: encodeFunctionData({ abi: sticky3TokenAbi, functionName: x.poke ? "poke" : "play", args: [x.data] }) };
+        return run({ token: x.token, wallet: x.wallet, calls: [t], pools: await poolsOf(x.token) });
+    }
+    /** Any request the SDK builds (ph.modes.*.build, ph.sticky3.build.*), as `wallet`. */
+    async function tx(x) {
+        return run({ token: x.token, wallet: x.wallet, calls: [x.tx], bnb: x.tx.value, pools: await poolsOf(x.token) });
+    }
+    return { buy, sell, send, play, tx, shadowOf, eventText };
+}

package/dist/sticky-sim.d.ts

@@ -0,0 +1,125 @@
+/**
+ * sticky rules in the browser: the coin's rule engine (src/sticky/StickyToken.sol) line for line, on bigints, and a test
+ * run of random trades on top. The engine is checked against the contract trade by trade (test/sticky/StickyTrace.t.sol
+ * writes a run, scripts/dev/sticky-sim-diff.mjs replays it here), so what the launcher shows is what the coin would do.
+ * The chain stays the truth: this only shows a creator what a table does before the launch.
+ */
+import { type Row } from "./sticky-rules.js";
+export declare const SUPPLY: bigint;
+/** The addresses the coin does not keep lots for. */
+export declare const POOL = "pool";
+export declare const POT = "pot";
+export declare const DEAD = "dead";
+export type Lot = {
+    amount: bigint;
+    lk: bigint;
+    since: number;
+    flags: number;
+};
+export type Stats = {
+    holders: number;
+    buys: number;
+    sells: number;
+    highAt: number;
+    lastBuy: number;
+    volume: bigint;
+    net: bigint;
+    peak: bigint;
+    high: bigint;
+};
+export type Now = {
+    t: number;
+    b: number;
+};
+export type CoinState = {
+    rows: Row[];
+    release: number;
+    off: number;
+    creator: string;
+    start: number;
+    startBlock: number;
+    curveSupply: bigint;
+    stats: Stats;
+    bal: Map<string, bigint>;
+    lots: Map<string, Lot[]>;
+};
+export type Result = {
+    ok: true;
+    burn: bigint;
+    toPot: bigint;
+    drop: bigint;
+} | {
+    ok: false;
+    why: number | "nope";
+};
+export declare function newCoin(rows: (bigint | Row)[], release: number, creator: string, curveSupply: bigint, start?: number, startBlock?: number): CoinState;
+/** A transfer as the coin runs it: out of POOL is a buy, into POOL a sell, anything else a send. */
+export declare function transfer(s: CoinState, from: string, to: string, amount: bigint, now: Now): Result;
+/** What `a` could sell right now (size rows left out, like the coin's view). */
+export declare function sellable(s: CoinState, a: string, now: Now): bigint;
+export declare function balanceOf(s: CoinState, a: string): bigint;
+export declare function lots(s: CoinState, a: string): Lot[];
+/** The curve as the coin prices it: x * y = k from the start price, so price / start = (supply / coins left)². */
+export declare const CURVE: {
+    supply: bigint;
+    startFdvBnb: number;
+};
+export type SimReport = {
+    trades: number;
+    hours: number;
+    buys: {
+        ok: number;
+        refused: number;
+    };
+    sells: {
+        ok: number;
+        refused: number;
+    };
+    sends: {
+        ok: number;
+        refused: number;
+    };
+    /** refusals by row (0 based) and LOCKED (254) */
+    refusals: {
+        row: number;
+        count: number;
+    }[];
+    /** longest a wallet that wanted to sell had to wait until a sell went through (seconds) */
+    longestWait: number;
+    /** wallets still unable to sell when the run ended */
+    stillWaiting: number;
+    /** after the run: seconds until every wallet can sell everything (null: longer than 31 days) */
+    allFreeAfter: number | null;
+    burnedPct: number;
+    pot: {
+        inPct: number;
+        drops: number;
+        paidPct: number;
+        biggestX: number;
+        leftPct: number;
+    };
+    snipers: {
+        count: number;
+        firstSellAfter: number | null;
+    };
+    splits: {
+        count: number;
+        refusedAfter: number;
+    };
+    /** a scanner's test: a tiny buy and an instant sell an hour after launch */
+    scanner: {
+        buy: number | null;
+        sell: number | null;
+    };
+};
+/**
+ * Random trades on a fresh coin with this table: the creator's first buy, three snipers in the first blocks, wallets
+ * that come, buy, hold for a while and sell (and try again when refused), some bags split to fresh wallets that then
+ * try to sell. The same seed gives the same run.
+ */
+export declare function simulate(rows: bigint[], release: number, opts?: {
+    seed?: number;
+    trades?: number;
+    devBuyBnb?: number;
+    start?: number;
+}): SimReport;