@pickhooks/sdk 0.4.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.d.ts

@@ -1,4 +1,6 @@
 import { type Address, type Hex } from "viem";
+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";
@@ -54,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;
@@ -102,6 +111,9 @@ export type StickyLaunch = {
      */
     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;
@@ -145,13 +157,16 @@ export declare function stickyTestRun(l: Pick<StickyLaunch, "picks" | "script" |
 }): 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).
+ * 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, v2?: boolean): {
+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;
@@ -182,6 +197,7 @@ export declare function stickyModule(ctx: Ctx, v2?: boolean): {
         balance: bigint;
         sellable: bigint;
         lots: StickyLot[];
+        held?: bigint;
     }>;
     check: (c: {
         token: Address;
@@ -202,6 +218,7 @@ export declare function stickyModule(ctx: Ctx, v2?: boolean): {
         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: {
@@ -215,6 +232,8 @@ export declare function stickyModule(ctx: Ctx, v2?: boolean): {
             minCreatorBps: number;
             switcher?: Address;
             switchMask?: number;
+            mode?: ModeName;
+            modeSettings?: ModeSettings;
         }, value: bigint) => TxRequest;
         buy: (b: {
             token: Address;