@pickhooks/sdk 0.0.0-stage → 0.2.0

package/dist/sticky.d.ts

@@ -0,0 +1,216 @@
+import { type Address, type Hex } from "viem";
+import { type EditRow, type Pick, compile } from "./sticky-rules.js";
+import { type Ctx, type SendOptions, type Sent, type TxRequest } from "./tx.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; or rows + release for a table built elsewhere */
+    picks?: Pick[];
+    /**
+     * 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;
+};
+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[];
+export declare function stickyModule(ctx: Ctx): {
+    factory: `0x${string}`;
+    terms: () => Promise<StickyTerms>;
+    validate: (rows: bigint[], release: number, custom?: boolean) => Promise<string | null>;
+    compile: typeof compile;
+    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;
+    }>;
+    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;
+        }, 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;
+    };
+    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;
+    }, s?: SendOptions) => Promise<Sent & {
+        quoted: bigint;
+        minOut: bigint;
+        amountOut: bigint;
+    }>;
+    sell: (x: {
+        token: Address;
+        amount: bigint;
+        slippageBps?: number;
+        minOut?: bigint;
+        deadline?: bigint;
+    }, s?: SendOptions) => Promise<Sent & {
+        quoted: bigint;
+        minOut: bigint;
+    }>;
+    lift: (token: Address, row: number, s?: SendOptions) => Promise<Sent>;
+    /** the sender's address, for callers that check before they sign */
+    from: (s?: SendOptions) => Promise<`0x${string}` | undefined>;
+};
+export type StickyModule = ReturnType<typeof stickyModule>;

package/dist/sticky.js

@@ -0,0 +1,292 @@
+import { encodeFunctionData, parseEventLogs } from "viem";
+import { stickyFactoryAbi, stickyTokenAbi, stickyValidatorAbi } from "./abis/sticky.js";
+import { v3PoolAbi } from "./abis/common.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 { approvalFor, buildV3Buy, buildV3Sell, receivedOf, v3EstimateBuy, v3PriceBnb, v3Quote } from "./v3.js";
+const randomSalt = () => {
+    const b = new Uint8Array(32);
+    globalThis.crypto.getRandomValues(b);
+    return `0x${Array.from(b, (x) => x.toString(16).padStart(2, "0")).join("")}`;
+};
+const toBase64 = (bytes) => {
+    const B = globalThis.Buffer;
+    if (B)
+        return B.from(bytes).toString("base64");
+    let s = "";
+    for (const x of bytes)
+        s += String.fromCharCode(x);
+    return btoa(s);
+};
+/** The rows of a coin as sentences, with the template each belongs to. */
+export function describeRows(raw, release, off) {
+    return raw.map((x, i) => {
+        const r = decodeRow(x);
+        const id = templateOf(r);
+        const t = id ? TEMPLATE_BY_ID.get(id) : null;
+        const name = r.act === ACT.POT ? "Pot" : (t?.name ?? "Custom row");
+        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) {
+    const { pub, a } = ctx;
+    const FA = stickyFactoryAbi;
+    const TA = stickyTokenAbi;
+    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 });
+        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. */
+    async function validate(rows, release, custom) {
+        const t = custom === undefined ? await terms() : null;
+        try {
+            await call(t?.validator ?? a.stickyValidator, stickyValidatorAbi, "validate", [rows, release, custom ?? t.custom]);
+            return null;
+        }
+        catch (e) {
+            return explain(e, "The validator refused this table.").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.
+     */
+    async function prepareMetadata(m) {
+        const res = await fetch(`${ctx.site}/api/sticky/prepare`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ ...m, image: { mime: m.image.mime, base64: toBase64(m.image.bytes) } }),
+        });
+        const j = (await res.json().catch(() => ({})));
+        if (!res.ok || !j.metadata)
+            throw new PickhooksError(j.error ?? `The site answered ${res.status}.`, { code: "site" });
+        return { metadata: j.metadata, image: j.image ?? "" };
+    }
+    /** 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" };
+    }
+    /** 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 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 sent = await sendTx(ctx, tx, s);
+        const ev = parseEventLogs({ abi: FA, logs: sent.receipt.logs, 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 };
+    }
+    const FIELDS = ["name", "symbol", "metadata", "creator", "pool", "pool2", "start", "stats", "script", "pot", "totalSupply"];
+    async function summaries(tokens) {
+        if (!tokens.length)
+            return [];
+        const per = FIELDS.length;
+        const res = await pub.multicall({ contracts: tokens.flatMap((t) => FIELDS.map((functionName) => ({ address: t, abi: TA, functionName }))), allowFailure: true });
+        const pools = tokens.map((_, i) => res[i * per + 4].result);
+        const slots = await pub.multicall({
+            contracts: pools.map((p) => ({ address: (p ?? a.wbnb), abi: v3PoolAbi, functionName: "slot0" })),
+            allowFailure: true,
+        });
+        const out = [];
+        tokens.forEach((token, i) => {
+            const g = (k) => res[i * per + k];
+            if (g(0).status !== "success" || !pools[i] || g(8).status !== "success")
+                return;
+            const stats = g(7).result;
+            const [raw, release, off] = g(8).result;
+            const supply = g(10).result ?? 10n ** 27n;
+            const sl = slots[i];
+            const priceBnb = sl.status === "success" ? v3PriceBnb(sl.result[0], token, a.wbnb) : 0;
+            out.push({
+                token,
+                name: String(g(0).result ?? ""),
+                symbol: String(g(1).result ?? ""),
+                metadata: String(g(2).result ?? ""),
+                creator: g(3).result,
+                pool: pools[i],
+                pair: g(5).result ?? ZERO_ADDRESS,
+                start: Number(g(6).result ?? 0),
+                release: Number(release),
+                rows: describeRows(raw, Number(release), Number(off)),
+                scanner: scannerOf(raw.map(decodeRow)),
+                holders: Number(stats[0]),
+                buys: Number(stats[1]),
+                sells: Number(stats[2]),
+                lastBuy: Number(stats[4]),
+                volume: stats[5],
+                pot: g(9).result ?? 0n,
+                totalSupply: supply,
+                priceBnb,
+                mcapBnb: priceBnb * (Number(supply) / 1e18),
+            });
+        });
+        return out;
+    }
+    /** How many coins the factory launched. */
+    const count = async () => Number(await call(a.stickyFactory, FA, "coinCount"));
+    /** Coins newest first: `limit` of them, skipping the newest `offset`. */
+    async function coins(o = {}) {
+        const n = await count();
+        const end = Math.max(0, n - (o.offset ?? 0));
+        const from = Math.max(0, end - (o.limit ?? 50));
+        if (end <= from)
+            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] })),
+            allowFailure: false,
+        }));
+        return summaries(tokens);
+    }
+    const isCoin = async (token) => (await call(a.stickyFactory, 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)))
+            return null;
+        return (await summaries([token]))[0] ?? null;
+    }
+    /** A wallet's lots (amount, locked part, since, marks), its balance and what it can sell now. */
+    async function wallet(token, who) {
+        const r = await pub.multicall({
+            contracts: [
+                { address: token, abi: TA, functionName: "balanceOf", args: [who] },
+                { address: token, abi: TA, functionName: "sellable", args: [who] },
+                { address: token, abi: TA, functionName: "lotsOf", args: [who] },
+            ],
+            allowFailure: false,
+        });
+        const [amount, locked, since, flags, open] = r[2];
+        return {
+            balance: r[0],
+            sellable: r[1],
+            lots: amount.map((x, i) => ({ amount: x, locked: locked[i], since: Number(since[i]), flags: Number(flags[i]), open: open[i] })),
+        };
+    }
+    /**
+     * Would this trade go through: the coin's own check(), the same code a transfer runs. For a buy pass the coins it would
+     * get (a quote is fine: the size rows look at a share of the supply). A send is checked from `wallet` to `to`.
+     */
+    async function check(c) {
+        const args = c.side === "buy" ? [ON.BUY, ZERO_ADDRESS, c.wallet, c.amount] : c.side === "sell" ? [ON.SELL, c.wallet, ZERO_ADDRESS, c.amount] : [ON.SEND, c.wallet, c.to ?? ZERO_ADDRESS, c.amount];
+        const [r, script] = await Promise.all([call(c.token, TA, "check", args), call(c.token, TA, "script")]);
+        const answer = Number(r);
+        if (answer === NONE)
+            return { ok: true };
+        if (answer === LOCKED) {
+            // the coin answers "locked" too when the wallet simply holds fewer coins than the trade
+            const held = c.side === "buy" ? null : await call(c.token, TA, "balanceOf", [c.wallet]).catch(() => null);
+            const text = held !== null && held < c.amount ? "This wallet holds fewer of these coins than that." : errorText("Blocked", [LOCKED]);
+            return { ok: false, row: "locked", text, rule: null };
+        }
+        const rows = describeRows(script[0], Number(script[1]), Number(script[2]));
+        const rule = rows[answer] ?? null;
+        return { ok: false, row: answer, text: `Refused by rule ${answer + 1}${rule ? `: ${rule.name}. ${rule.text}` : "."}`, rule };
+    }
+    /** Coins a buy of `bnbIn` would get, estimated from the pool's liquidity at its price (see v3EstimateBuy); not a minOut. */
+    async function estimateBuy(token, bnbIn) {
+        return v3EstimateBuy(ctx, await call(token, TA, "pool"), token, bnbIn);
+    }
+    /**
+     * What a trade gets in the V3 pool, from PancakeSwap's QuoterV2. It runs the swap, so a refusing rule fails it, and it
+     * 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).
+     */
+    async function quote(q) {
+        try {
+            return { amountOut: await v3Quote(ctx, q) };
+        }
+        catch (e) {
+            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;
+                if (c && !c.ok)
+                    throw new PickhooksError(c.text, { code: "Blocked", args: [c.row === "locked" ? LOCKED : c.row], cause: e });
+            }
+            throw toPickhooksError(e, "The quoter refused this trade.");
+        }
+    }
+    /** A buy through PancakeSwap's V3 SwapRouter, BNB in (wrapped by the router). */
+    const buildBuy = (b) => buildV3Buy(a, b);
+    /** A sell through the V3 SwapRouter for native BNB: swap to the router, unwrap to the seller. Needs approval to the router. */
+    const buildSell = (x) => buildV3Sell(a, x);
+    /** The approval a sell needs (the coin to the V3 router), or null. */
+    const sellApproval = (owner, token, amount) => approvalFor(ctx, owner, token, amount, a.v3Router, "Allowing PancakeSwap");
+    const refuse = (c) => {
+        if (!c.ok)
+            throw new PickhooksError(c.text, { code: "Blocked", args: [c.row === "locked" ? LOCKED : c.row] });
+    };
+    /** 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) };
+    }
+    /** 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);
+        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 };
+    }
+    /** 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}` });
+    return {
+        factory: a.stickyFactory,
+        terms,
+        validate,
+        compile,
+        describeRows,
+        prepareMetadata,
+        count,
+        coins,
+        coin,
+        isCoin,
+        wallet,
+        check,
+        quote,
+        estimateBuy,
+        sellApproval,
+        build: { launch: buildLaunch, buy: buildBuy, sell: buildSell, lift: buildLift },
+        launch,
+        buy,
+        sell,
+        lift: (token, row, s = {}) => sendTx(ctx, buildLift(token, row), s),
+        /** the sender's address, for callers that check before they sign */
+        from: (s = {}) => senderAddress(ctx, s.wallet),
+    };
+}

package/dist/tx.d.ts

@@ -0,0 +1,70 @@
+import { type Account, type Address, type Hex, type PublicClient, type TransactionReceipt, type WalletClient } from "viem";
+import { type Addresses } from "./addresses.js";
+/**
+ * A transaction as plain data: send it with any wallet, wrap it in a multicall, or route it through your own contract.
+ * `extraGas` is what to add on top of your own gas estimate (the recapture room of a hook any coin trade); it never
+ * changes what the call does, only whether the hook has gas left to close a gap after the swap.
+ */
+export type TxRequest = {
+    to: Address;
+    data: Hex;
+    value: bigint;
+    extraGas?: bigint;
+    /** the estimate is taken times this percentage (default 130); trades that liquidate or count rules can grow while they wait */
+    gasPct?: number;
+    /** what it does, in words (for logs and confirmations) */
+    label?: string;
+};
+export type SendOptions = {
+    /** sends from this wallet instead of the client's */
+    wallet?: WalletClient;
+    /** a fixed gas limit instead of estimate x 1.3 + extraGas */
+    gas?: bigint;
+    /** called with the hash as soon as the wallet returns it */
+    onHash?: (hash: Hex) => void;
+    /** how long to wait for the receipt, ms (default 120 s) */
+    timeout?: number;
+};
+export type Sent = {
+    hash: Hex;
+    receipt: TransactionReceipt;
+};
+export type PickhooksOptions = {
+    /** a viem public client on BNB Chain (or a fork of it); without it the SDK makes one from rpcUrl */
+    publicClient?: PublicClient;
+    /** used when no publicClient is given; default BNB Chain's public RPC */
+    rpcUrl?: string;
+    /** signs and sends; only the write methods need it */
+    walletClient?: WalletClient;
+    /** other contract addresses (a fork rehearsal, a new factory); merged over BSC_MAINNET */
+    addresses?: Partial<Addresses>;
+    /** the pickhooks site for its public API and partner links (default https://pickhooks.com) */
+    site?: string;
+};
+/** What every module of the SDK shares. */
+export type Ctx = {
+    pub: PublicClient;
+    wallet?: WalletClient;
+    a: Addresses;
+    site: string;
+};
+export declare const DEFAULT_RPC = "https://bsc-dataseed.bnbchain.org";
+export declare function makeCtx(o?: PickhooksOptions): Ctx;
+/** The wallet a write goes out from, and its account (a local account signs locally, an address goes to the wallet). */
+export declare function signer(ctx: Ctx, w?: WalletClient): Promise<{
+    wallet: WalletClient;
+    account: Account | Address;
+    address: Address;
+}>;
+/** The address a write would go out from (for quotes and checks before it), or undefined without a wallet. */
+export declare function senderAddress(ctx: Ctx, w?: WalletClient): Promise<Address | undefined>;
+/** The gas limit a request goes out with: estimate x gasPct (default 130 %) plus its extraGas, never above what BNB Chain accepts. */
+export declare function gasFor(ctx: Ctx, tx: TxRequest, from: Address): Promise<bigint>;
+/** Estimates, sends and waits for the receipt; a failure comes back as a PickhooksError with a sentence. */
+export declare function sendTx(ctx: Ctx, tx: TxRequest, o?: SendOptions): Promise<Sent>;
+/** Sends requests one after the other (approvals before a trade). */
+export declare function sendAll(ctx: Ctx, txs: TxRequest[], o?: SendOptions): Promise<Sent[]>;
+/** A deadline 10 minutes from now (seconds), for router calls. */
+export declare const deadlineIn: (seconds?: number) => bigint;
+/** amount less a slippage in basis points */
+export declare const minusBps: (amount: bigint, bps: number) => bigint;

package/dist/tx.js

@@ -0,0 +1,69 @@
+import { createPublicClient, http, } from "viem";
+import { bsc } from "viem/chains";
+import { BSC_MAINNET, LIMITS } from "./addresses.js";
+import { PickhooksError, toPickhooksError } from "./errors.js";
+export const DEFAULT_RPC = "https://bsc-dataseed.bnbchain.org";
+export function makeCtx(o = {}) {
+    const pub = o.publicClient ?? createPublicClient({ chain: bsc, transport: http(o.rpcUrl ?? DEFAULT_RPC, { batch: true }) });
+    return { pub, wallet: o.walletClient, a: { ...BSC_MAINNET, ...o.addresses }, site: (o.site ?? "https://pickhooks.com").replace(/\/$/, "") };
+}
+/** The wallet a write goes out from, and its account (a local account signs locally, an address goes to the wallet). */
+export async function signer(ctx, w) {
+    const wallet = w ?? ctx.wallet;
+    if (!wallet)
+        throw new PickhooksError("This needs a wallet: pass walletClient to createPickhooks or { wallet } to the call.", { code: "input" });
+    const account = wallet.account ?? (await wallet.getAddresses())[0];
+    if (!account)
+        throw new PickhooksError("The wallet has no account.", { code: "input" });
+    return { wallet, account, address: typeof account === "string" ? account : account.address };
+}
+/** The address a write would go out from (for quotes and checks before it), or undefined without a wallet. */
+export async function senderAddress(ctx, w) {
+    const wallet = w ?? ctx.wallet;
+    if (!wallet)
+        return undefined;
+    if (wallet.account)
+        return wallet.account.address;
+    return (await wallet.getAddresses())[0];
+}
+/** The gas limit a request goes out with: estimate x gasPct (default 130 %) plus its extraGas, never above what BNB Chain accepts. */
+export async function gasFor(ctx, tx, from) {
+    let est;
+    try {
+        est = await ctx.pub.estimateGas({ account: from, to: tx.to, data: tx.data, value: tx.value });
+    }
+    catch (e) {
+        throw toPickhooksError(e, `${tx.label ?? "The transaction"} would fail.`);
+    }
+    const gas = (est * BigInt(tx.gasPct ?? 130)) / 100n + (tx.extraGas ?? 0n);
+    return gas > LIMITS.gasCap ? LIMITS.gasCap : gas;
+}
+/** Estimates, sends and waits for the receipt; a failure comes back as a PickhooksError with a sentence. */
+export async function sendTx(ctx, tx, o = {}) {
+    const { wallet, account, address } = await signer(ctx, o.wallet);
+    const gas = o.gas ?? (await gasFor(ctx, tx, address));
+    let hash;
+    try {
+        hash = await wallet.sendTransaction({ account, chain: (wallet.chain ?? bsc), to: tx.to, data: tx.data, value: tx.value, gas });
+    }
+    catch (e) {
+        throw toPickhooksError(e, `${tx.label ?? "The transaction"} was not sent.`);
+    }
+    o.onHash?.(hash);
+    const receipt = await ctx.pub.waitForTransactionReceipt({ hash, timeout: o.timeout ?? 120_000 });
+    if (receipt.status !== "success") {
+        throw new PickhooksError(`${tx.label ?? "The transaction"} failed on chain (${hash}).`, { code: "reverted", hash });
+    }
+    return { hash, receipt };
+}
+/** Sends requests one after the other (approvals before a trade). */
+export async function sendAll(ctx, txs, o = {}) {
+    const out = [];
+    for (const tx of txs)
+        out.push(await sendTx(ctx, tx, o));
+    return out;
+}
+/** A deadline 10 minutes from now (seconds), for router calls. */
+export const deadlineIn = (seconds = 600) => BigInt(Math.floor(Date.now() / 1000) + seconds);
+/** amount less a slippage in basis points */
+export const minusBps = (amount, bps) => (amount * BigInt(10_000 - Math.max(0, Math.min(10_000, Math.round(bps))))) / 10000n;