@pickhooks/sdk 0.0.0-stage → 0.4.0

package/dist/sticky.d.ts

@@ -0,0 +1,286 @@
+import { type Address, type Hex } from "viem";
+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
+ * validator checks the table at launch and the coin checks every transfer. Sticky coins trade in a PancakeSwap V3 pool
+ * of 1 % (plus a V2 pair), so any router can trade them; check() names the row that would stop a trade before it is sent.
+ */
+export type StickyRow = {
+    /** 0 based; the site and errors say "rule i + 1" */
+    i: number;
+    /** the template's name, "Pot", or "Custom row" */
+    name: string;
+    /** the row as a sentence */
+    text: string;
+    template: string | null;
+    /** true when the rule moves with the coins */
+    sticky: boolean;
+    lock: boolean;
+    drop: boolean;
+    /** the creator lifted it for good */
+    lifted: boolean;
+    /** the raw row (uint256) */
+    raw: bigint;
+};
+export type StickyCoin = {
+    token: Address;
+    name: string;
+    symbol: string;
+    /** the metadata link (JSON with image, description, links) */
+    metadata: string;
+    creator: Address;
+    /** the PancakeSwap V3 pool (1 %) and the V2 pair */
+    pool: Address;
+    pair: Address;
+    start: number;
+    /** seconds a LOCK row's coins take to unlock */
+    release: number;
+    rows: StickyRow[];
+    /** how scanners see the table: green nothing, yellow a warning, red a refused test sell at times */
+    scanner: "green" | "yellow" | "red";
+    holders: number;
+    buys: number;
+    sells: number;
+    lastBuy: number;
+    /** BNB volume (wei) */
+    volume: bigint;
+    /** coins in the pot (POT rows fill it, DROP rows pay it out) */
+    pot: bigint;
+    totalSupply: bigint;
+    /** BNB per coin at the V3 pool's price, and the market cap in BNB */
+    priceBnb: number;
+    mcapBnb: number;
+};
+export type StickyLot = {
+    amount: bigint;
+    locked: bigint;
+    since: number;
+    flags: number;
+    open: boolean;
+};
+export type StickyCheck = {
+    ok: true;
+} | {
+    ok: false;
+    /** the row that stops it (0 based), or "locked": no row stops it but the coins are not unlocked yet */
+    row: number | "locked";
+    /** "Refused by rule 2: Sniper jail." and the row's sentence */
+    text: string;
+    rule: StickyRow | null;
+};
+export type StickyLaunch = {
+    name: string;
+    symbol: string;
+    /** a link to the coin's metadata JSON (name, symbol, description, image, website, twitter, telegram) */
+    metadata: string;
+    /** 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.
+     */
+    script?: EditRow[];
+    /** hook script rows that lock shares: hours until they unlock (10 minutes to 30 days); the longer release wins */
+    scriptHours?: number;
+    rows?: bigint[];
+    release?: number;
+    /** the creator's first buy (BNB wei); the DEV mark and the dev lock apply to it */
+    devBuy?: bigint;
+    /** share of the creator side the creator keeps (default 10000); the rest buys back and burns $hooks */
+    keepBps?: number;
+    /** a fixed salt (bytes32); default random */
+    salt?: Hex;
+    /**
+     * sticky 2 only: rules (0 based) that switch, 2 to 4 drop rows; one of them is on at a time (the first at launch) and
+     * the switcher turns another on. Default switcher: the rule auction, where holders burn coins to pick the game.
+     */
+    switchRows?: number[];
+    switcher?: Address;
+};
+export type StickyTerms = {
+    seed: bigint;
+    creatorBps: number;
+    custom: boolean;
+    validator: Address;
+    startFdv: bigint;
+    platformWallet: Address;
+    locker: Address;
+};
+/** 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[];
+/**
+ * The table a launch would send: the templates' rows, then the hook script rows (the site's order), one release time per
+ * coin (the longer one wins); or rows + release as given. Offline; throws the problems as sentences.
+ */
+export declare function stickyTable(l: Pick<StickyLaunch, "picks" | "script" | "scriptHours" | "rows" | "release">): {
+    rows: bigint[];
+    release: number;
+};
+export type StickyTestRun = {
+    rows: bigint[];
+    release: number;
+    /** the run's numbers, as the launcher's test run shows them */
+    report: SimReport;
+    /** the run as sentences, one per line of the launcher's card */
+    text: string[];
+};
+/** A test run as sentences: the launcher's card line by line. `names` are the rows' names (rule i + 1). */
+export declare function testRunText(r: SimReport, names: string[]): string[];
+/**
+ * The launcher's test run, offline: the table on a fresh coin with random trades (the creator's first buy, three snipers
+ * in the first blocks, wallets that buy, hold and sell, bags split to fresh wallets). It runs the coin's own rule engine,
+ * checked against the contract trade by trade. The same seed gives the same run; the chain stays the truth.
+ */
+export declare function stickyTestRun(l: Pick<StickyLaunch, "picks" | "script" | "scriptHours" | "rows" | "release"> & {
+    devBuyBnb?: number;
+    seed?: number;
+    trades?: number;
+    start?: number;
+}): StickyTestRun;
+/**
+ * The sticky module. `v2` points it at the sticky 2 factory (same coins, same rules, same calls; its coins also count
+ * the creator's sold coins and can carry switch rows, see ph.sticky2).
+ */
+export declare function stickyModule(ctx: Ctx, v2?: boolean): {
+    factory: `0x${string}`;
+    terms: () => Promise<StickyTerms>;
+    validate: (rows: bigint[], release: number, custom?: boolean) => Promise<string | null>;
+    validateSwitch: (rows: bigint[], mask: number, validator?: Address) => Promise<string | null>;
+    compile: typeof compile;
+    table: typeof stickyTable;
+    testRun: typeof stickyTestRun;
+    describeRows: typeof describeRows;
+    prepareMetadata: (m: {
+        name: string;
+        symbol: string;
+        description?: string;
+        website?: string;
+        twitter?: string;
+        telegram?: string;
+        image: {
+            mime: "image/png" | "image/jpeg" | "image/webp" | "image/gif";
+            bytes: Uint8Array;
+        };
+    }) => Promise<{
+        metadata: string;
+        image: string;
+    }>;
+    count: () => Promise<number>;
+    coins: (o?: {
+        limit?: number;
+        offset?: number;
+    }) => Promise<StickyCoin[]>;
+    coin: (token: Address) => Promise<StickyCoin | null>;
+    isCoin: (token: Address) => Promise<boolean>;
+    wallet: (token: Address, who: Address) => Promise<{
+        balance: bigint;
+        sellable: bigint;
+        lots: StickyLot[];
+    }>;
+    check: (c: {
+        token: Address;
+        side: "buy" | "sell" | "send";
+        wallet: Address;
+        amount: bigint;
+        to?: Address;
+    }) => Promise<StickyCheck>;
+    quote: (q: {
+        token: Address;
+        side: "buy" | "sell";
+        amount: bigint;
+        wallet?: Address;
+    }) => Promise<{
+        amountOut: bigint;
+        venue: Venue;
+        v3: bigint | null;
+        v2: bigint | null;
+    }>;
+    estimateBuy: (token: Address, bnbIn: bigint) => Promise<bigint>;
+    sellApproval: (owner: Address, token: Address, amount: bigint) => Promise<TxRequest | null>;
+    build: {
+        launch: (l: {
+            name: string;
+            symbol: string;
+            metadata: string;
+            rows: bigint[];
+            release: number;
+            salt?: Hex;
+            keepBps?: number;
+            minCreatorBps: number;
+            switcher?: Address;
+            switchMask?: number;
+        }, value: bigint) => TxRequest;
+        buy: (b: {
+            token: Address;
+            bnbIn: bigint;
+            minOut: bigint;
+            recipient: Address;
+            deadline?: bigint;
+        }) => TxRequest;
+        sell: (x: {
+            token: Address;
+            amount: bigint;
+            minOut: bigint;
+            recipient: Address;
+            deadline?: bigint;
+        }) => TxRequest;
+        lift: (token: Address, row: number) => TxRequest;
+        collect: (token: Address) => Promise<TxRequest>;
+    };
+    launch: (l: StickyLaunch, s?: SendOptions) => Promise<Sent & {
+        token: Address;
+        pool: Address;
+        pair: Address;
+        rows: bigint[];
+        release: number;
+    }>;
+    buy: (b: {
+        token: Address;
+        bnbIn: bigint;
+        slippageBps?: number;
+        minOut?: bigint;
+        deadline?: bigint;
+        venue?: Venue;
+    }, s?: SendOptions) => Promise<Sent & {
+        quoted: bigint;
+        minOut: bigint;
+        amountOut: bigint;
+        venue: Venue;
+    }>;
+    sell: (x: {
+        token: Address;
+        amount: bigint;
+        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>;
+};
+export type StickyModule = ReturnType<typeof stickyModule>;