@pickhooks/sdk 0.0.0-stage → 0.2.0

package/dist/api.d.ts

@@ -0,0 +1,62 @@
+import type { Address, Hex } from "viem";
+import type { BlocksCatalog } from "./blocks.js";
+import type { Ctx } from "./tx.js";
+/**
+ * pickhooks.com's public JSON API (GET only, no key, CORS open; documented at /docs/api). Each address has a limit per
+ * minute (launches 240, coins and activity 120, official 60); a few calls per second is plenty. Answers are typed loosely:
+ * the site adds fields over time, the SDK only names the ones it promises.
+ */
+/** One coin of the launch feed (a row of /api/launches). */
+export type Launch = {
+    token: Address;
+    factory: Address;
+    launcher: Address;
+    /** rules, pools, calls, lever, flap, sticky, ... */
+    mode: string;
+    creator: Address;
+    createdAt: number;
+    block?: number;
+    tx?: Hex;
+    name: string;
+    symbol: string;
+    image?: string;
+    pool?: string;
+    pair?: Address;
+    rules?: {
+        kind: number;
+        name: string;
+        text: string;
+    }[];
+    [k: string]: unknown;
+};
+export type LaunchFeed = {
+    launches: Launch[];
+    factories?: unknown[];
+    [k: string]: unknown;
+};
+export declare function apiModule(ctx: Ctx): {
+    get: <T>(path: string, query?: Record<string, string | number | undefined>) => Promise<T>;
+    /** every coin, newest first; poll with since = the newest createdAt you have, page back with before */
+    launches: (o?: {
+        since?: number;
+        before?: number;
+        limit?: number;
+    }) => Promise<LaunchFeed>;
+    /** one coin by any of its addresses (token, pool, pair) */
+    launch: (address: Address) => Promise<Launch>;
+    /** the board's coins; board: 1 adds lever, calls and find the dev coins */
+    coins: (o?: {
+        board?: 1;
+    }) => Promise<unknown>;
+    /** buybacks, burns, jackpots and launches, newest first */
+    activity: (o?: {
+        kind?: string;
+        limit?: number;
+    }) => Promise<unknown>;
+    /** $hooks: buybacks and burns of the pad's fees */
+    official: () => Promise<unknown>;
+    burners: () => Promise<unknown>;
+    /** the building blocks catalog as the site serves it (the same object as ph.blocks.catalog(), offline) */
+    blocks: () => Promise<BlocksCatalog>;
+};
+export type ApiModule = ReturnType<typeof apiModule>;

package/dist/api.js

@@ -0,0 +1,30 @@
+import { PickhooksError } from "./errors.js";
+export function apiModule(ctx) {
+    async function get(path, query = {}) {
+        const q = Object.entries(query)
+            .filter(([, v]) => v !== undefined && v !== "")
+            .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`)
+            .join("&");
+        const res = await fetch(`${ctx.site}${path}${q ? `?${q}` : ""}`, { headers: { accept: "application/json" } });
+        const j = (await res.json().catch(() => null));
+        if (!res.ok || j === null)
+            throw new PickhooksError(j?.error ?? `${path} answered ${res.status}.`, { code: res.status === 429 ? "rate" : "site" });
+        return j;
+    }
+    return {
+        get,
+        /** every coin, newest first; poll with since = the newest createdAt you have, page back with before */
+        launches: (o = {}) => get("/api/launches", o),
+        /** one coin by any of its addresses (token, pool, pair) */
+        launch: (address) => get(`/api/launches/${address}`),
+        /** the board's coins; board: 1 adds lever, calls and find the dev coins */
+        coins: (o = {}) => get("/api/coins", o),
+        /** buybacks, burns, jackpots and launches, newest first */
+        activity: (o = {}) => get("/api/activity", o),
+        /** $hooks: buybacks and burns of the pad's fees */
+        official: () => get("/api/official"),
+        burners: () => get("/api/burners"),
+        /** the building blocks catalog as the site serves it (the same object as ph.blocks.catalog(), offline) */
+        blocks: () => get("/api/blocks"),
+    };
+}

package/dist/blocks.d.ts

@@ -0,0 +1,107 @@
+import { STICKY_LIMITS } from "./sticky-rules.js";
+export declare const BLOCKS_VERSION = 1;
+export type BlockParam = {
+    key: string;
+    label: string;
+    unit: string;
+    min: number;
+    max: number;
+    step: number;
+    default: number;
+    hint: string;
+};
+export type Block = {
+    id: string;
+    name: string;
+    /** the block in a sentence, its numbers as {key} */
+    line: string;
+    /** the same sentence with the default numbers */
+    example: string;
+    /** the rule moves with the coins to every wallet */
+    sticky: boolean;
+    /** the block gives buyers something (the pot blocks) */
+    gives: boolean;
+    /** what token scanners show: green nothing, yellow a warning, red a refused test sell at times */
+    scanner: "green" | "yellow" | "red";
+    scannerNote: string;
+    params: BlockParam[];
+    /** the rows it adds to a coin's table at the default numbers, as the coin page reads them */
+    rows: string[];
+};
+export type GrammarItem = {
+    id: number;
+    name: string;
+    text: string;
+};
+export type BlockAction = GrammarItem & {
+    buysOnly: boolean;
+    arg: string;
+};
+export type BlockVariable = {
+    id: number;
+    name: string;
+    unit: string;
+    lotOnly: boolean;
+};
+export type CoinRuleField = {
+    id: string;
+    label: string;
+    kind: string;
+    min?: number;
+    max?: number;
+    default?: number | boolean;
+    hint?: string;
+    options?: {
+        value: number;
+        label: string;
+    }[];
+};
+export type CoinRuleBlock = {
+    kind: number;
+    id: string;
+    name: string;
+    alias?: string;
+    group: string;
+    line: string;
+    scanner: "green" | "yellow" | "red";
+    scannerNote: string;
+    fields: CoinRuleField[];
+};
+export type BlocksCatalog = {
+    version: number;
+    sticky: {
+        about: string;
+        promises: string[];
+        limits: Record<keyof typeof STICKY_LIMITS, number>;
+        blocks: Block[];
+        script: {
+            about: string;
+            triggers: GrammarItem[];
+            actions: BlockAction[];
+            marks: GrammarItem[];
+            variables: BlockVariable[];
+            operators: GrammarItem[];
+            checks: string[];
+        };
+    };
+    coinRules: {
+        about: string;
+        perCoin: number;
+        groups: {
+            id: string;
+            title: string;
+            blurb: string;
+        }[];
+        rules: CoinRuleBlock[];
+    };
+};
+/** A block's numbers for its sentence. Drip's {big} is a phrase, like in the launcher; pass the site's t() to translate it. */
+export declare function blockLineVars(id: string, p: Record<string, number>, phrase?: (s: string, v: Record<string, number>) => string): Record<string, string | number>;
+export declare const BLOCK_TRIGGERS: GrammarItem[];
+export declare const BLOCK_ACTIONS: BlockAction[];
+export declare const BLOCK_MARKS: GrammarItem[];
+export declare const BLOCK_OPERATORS: GrammarItem[];
+/** the editor's own sentences (sticky-rules rowProblems / tableProblems, the launcher), so the site's translations apply */
+export declare const BLOCK_CHECKS: string[];
+/** The whole catalog. Plain data: JSON for the API, the same object in the SDK. */
+export declare function blocksCatalog(): BlocksCatalog;

package/dist/blocks.js

@@ -0,0 +1,126 @@
+// Copied from web/src/lib/blocks.ts (the building blocks catalog the site serves at /api/blocks), with its two imports pointed
+// at the SDK's copies. Keep the two in step: node scripts/check-rules-copy.mjs compares them.
+// The pickhooks building blocks as data, for /api/blocks, the /blocks page and @pickhooks/sdk (a copy: sdk/src/blocks.ts,
+// checked by sdk/scripts/check-rules-copy.mjs). Built from the sources the launchers use, so it cannot drift: the ready
+// blocks of sticky rules (TEMPLATES), the hook script grammar for your own rows (triggers, actions, marks, variables,
+// operators, the checks the editor and the validator on chain run), and the rule book of coins with rules.
+import { GROUPS_SHOWN, MAX_RULES, RULES_SHOWN } from "./coin-rules.js";
+import { ACT, FLAG, ON, OP, STICKY_LIMITS, TEMPLATES, VARS, defaults, rowText } from "./sticky-rules.js";
+export const BLOCKS_VERSION = 1;
+const fill = (line, p) => line.replace(/\{(\w+)\}/g, (all, k) => (k in p ? String(p[k]) : all));
+/** A block's numbers for its sentence. Drip's {big} is a phrase, like in the launcher; pass the site's t() to translate it. */
+export function blockLineVars(id, p, phrase = fill) {
+    if (id !== "drip")
+        return p;
+    return { ...p, big: p.big > 0 ? phrase(" of {pct} % of the supply or more", { pct: p.big }) : "" };
+}
+function fieldOf(f) {
+    const out = { id: f.id, label: f.label, kind: f.kind };
+    if ("min" in f && f.min !== undefined)
+        out.min = f.min;
+    if ("max" in f && f.max !== undefined)
+        out.max = f.max;
+    if ("def" in f)
+        out.default = f.def;
+    if (f.hint)
+        out.hint = f.hint;
+    if (f.kind === "choice")
+        out.options = f.options;
+    return out;
+}
+export const BLOCK_TRIGGERS = [
+    { id: ON.BUY, name: "buy", text: "Coins leave one of the coin's pools to a wallet." },
+    { id: ON.SELL, name: "sell", text: "Coins go into one of the coin's pools." },
+    { id: ON.SEND, name: "send", text: "Coins move from one wallet to another. A row can watch several: buy, sell and send add up (3 = buy or sell)." },
+];
+export const BLOCK_ACTIONS = [
+    { id: ACT.DENY, name: "deny", text: "Refuses the trade.", buysOnly: false, arg: "none" },
+    { id: ACT.FLAG, name: "mark", text: "Marks the coins the buy brings. The mark travels with the coins to every wallet.", buysOnly: true, arg: "the mark: 1 sniper, 2 marked, 3 both" },
+    { id: ACT.LOCK, name: "lock", text: "A share of the buy unlocks over the coin's release time.", buysOnly: true, arg: "0.01 to 100 % of the buy, in basis points" },
+    { id: ACT.BURN, name: "burn", text: "Burns a share of the buy.", buysOnly: true, arg: "0.01 to 10 % of the buy, in basis points" },
+    { id: ACT.POT, name: "pot", text: "Puts a share of the buy into the coin's pot.", buysOnly: true, arg: "0.01 to 10 % of the buy, in basis points" },
+    { id: ACT.DROP, name: "drop", text: "Pays the buyer a share of the pot, up to as many coins as it buys. Never the creator's buys.", buysOnly: true, arg: "0.01 to 100 % of the pot, in basis points" },
+];
+export const BLOCK_MARKS = [
+    { id: FLAG.SNIPER, name: "sniper", text: "Set by a mark row, usually on buys in the first blocks." },
+    { id: FLAG.MARK, name: "marked", text: "Set by a mark row, for any condition you pick." },
+    { id: FLAG.DEV, name: "the creator's", text: "Set by the coin on the creator's coins. Rows can ask for it or exclude it." },
+];
+export const BLOCK_OPERATORS = [
+    { id: OP.LT, name: "under", text: "The variable is under the number." },
+    { id: OP.GE, name: "at least", text: "The variable is the number or more." },
+    { id: OP.HAS, name: "has", text: "The coins carry the mark." },
+    { id: OP.NOT, name: "not", text: "The coins do not carry the mark (only with the creator's mark)." },
+    { id: OP.MODLT, name: "inside a window", text: "A clock that repeats: inside the first part of every period (time since launch, a period of at most a day), or every n-th buy (buys)." },
+    { id: OP.MODGE, name: "outside a window", text: "The rest of each period, or the buys between." },
+];
+/** the editor's own sentences (sticky-rules rowProblems / tableProblems, the launcher), so the site's translations apply */
+export const BLOCK_CHECKS = [
+    `At most ${STICKY_LIMITS.maxRows} rows per coin, fixed at launch.`,
+    "Mark, lock, burn, pot and drop work on buys only.",
+    `Burn and pot: at most ${STICKY_LIMITS.maxTakePct} % of a buy together.`,
+    "A pot needs a drop row that pays it out.",
+    "A row that stops sells or sends must let go by itself: the coins' age or the time since launch up to 7 days, blocks since launch up to 1,000,000, a size from 0.05 % of the supply on, the creator's coins only, or a clock (one window, hours, weekdays).",
+    "One sell window at most, and not next to rows on hours or weekdays.",
+    "The rows on hours close every hour of the day: leave one open.",
+    "The rows on weekdays close every day: leave one open.",
+    `Locked shares: unlock over ${STICKY_LIMITS.minReleaseMinutes} minutes to ${STICKY_LIMITS.maxReleaseDays} days.`,
+    "The validator on chain runs the same checks on every table at launch.",
+];
+/** The whole catalog. Plain data: JSON for the API, the same object in the SDK. */
+export function blocksCatalog() {
+    const blocks = TEMPLATES.map((t) => {
+        const p = defaults(t);
+        const release = t.release?.(p) ?? 0;
+        return {
+            id: t.id,
+            name: t.name,
+            line: t.line,
+            example: fill(t.line, blockLineVars(t.id, p)),
+            sticky: t.sticky,
+            gives: !!t.gives,
+            scanner: t.scanner,
+            scannerNote: t.scannerNote ?? "",
+            params: t.params.map((q) => ({ key: q.key, label: q.label, unit: q.unit, min: q.min, max: q.max, step: q.step, default: q.def, hint: q.hint })),
+            rows: t.rows(p).map((r) => rowText(r, release)),
+        };
+    });
+    return {
+        version: BLOCKS_VERSION,
+        sticky: {
+            about: "Sticky rules: rows a coin checks on every buy, sell and send. They look at each lot of coins, not at the wallet, so a rule moves with the coins to every wallet. Ready blocks set the rows from a few numbers; hook script writes your own.",
+            promises: [
+                `Every lot can be sold once it is ${STICKY_LIMITS.exitDays} days old, whatever the rows say.`,
+                "Sells and sends are never taxed.",
+                "After launch the creator can lift a row for good, never add one.",
+            ],
+            limits: { ...STICKY_LIMITS },
+            blocks,
+            script: {
+                about: "A row is a trigger, an action with its number, and up to 4 conditions that must all hold. The coin goes through its rows in order on every transfer; the first row that refuses stops it.",
+                triggers: BLOCK_TRIGGERS,
+                actions: BLOCK_ACTIONS,
+                marks: BLOCK_MARKS,
+                variables: VARS.map((v) => ({ id: v.v, name: v.label, unit: v.unit, lotOnly: !!v.lotOnly })),
+                operators: BLOCK_OPERATORS,
+                checks: BLOCK_CHECKS,
+            },
+        },
+        coinRules: {
+            about: "Coins with rules: up to eight rules from the rule book live in the coin and apply to every transfer with its pool.",
+            perCoin: MAX_RULES,
+            groups: GROUPS_SHOWN.map((g) => ({ id: g.id, title: g.title, blurb: g.blurb })),
+            rules: RULES_SHOWN.map((r) => ({
+                kind: r.kind,
+                id: r.id,
+                name: r.name,
+                ...(r.alias ? { alias: r.alias } : {}),
+                group: r.group,
+                line: r.line,
+                scanner: r.scanner.level,
+                scannerNote: r.scanner.note,
+                fields: r.fields.map(fieldOf),
+            })),
+        },
+    };
+}

package/dist/coin-rules-config.d.ts

@@ -0,0 +1,8 @@
+/**
+ * What the copied rule catalog (coin-rules.ts) reads from the site's config: the v2 factory (the catalog shows the eight
+ * v2 rules when it is set) and the Chainlink USD feeds the v2 validator accepts for "sells at" (8 decimals).
+ */
+export declare const V2: {
+    readonly factory: `0x${string}`;
+    readonly feeds: Record<string, `0x${string}`>;
+};

package/dist/coin-rules-config.js

@@ -0,0 +1,13 @@
+/**
+ * What the copied rule catalog (coin-rules.ts) reads from the site's config: the v2 factory (the catalog shows the eight
+ * v2 rules when it is set) and the Chainlink USD feeds the v2 validator accepts for "sells at" (8 decimals).
+ */
+export const V2 = {
+    factory: "0x23cC366e1DDBc41CFD70011C4AaC14B79998B24F",
+    feeds: {
+        BNB: "0x0567F2323251f0Aab15c8dFb1967E4e8A7D42aeE",
+        BTC: "0x264990fbd0A4796A3E3d8E37C4d5F87a3aCa5Ebf",
+        ETH: "0x9ef1B8c0E4F7dc8bF5719Ea496883DC6401d5b2e",
+        DOGE: "0x3AB0A0d137D4F946fBB19eecc6e92E64660231C8",
+    },
+};