@pickhooks/sdk 0.0.0-stage → 0.2.0

package/dist/dips.js

@@ -0,0 +1,148 @@
+import { encodeFunctionData, parseEventLogs } from "viem";
+import { dipDeskAbi } from "./abis/dips.js";
+import { PickhooksError, toPickhooksError } from "./errors.js";
+import { minusBps, sendTx, signer } from "./tx.js";
+import { approvalFor } from "./v3.js";
+/** strike = BNB wei per whole coin, from a price in BNB per coin */
+export function strikeFromPrice(priceBnb) {
+    if (!(priceBnb > 0) || !Number.isFinite(priceBnb))
+        return 0n;
+    return BigInt(Math.max(1, Math.round(priceBnb * 1e18)));
+}
+/** BNB wei a floor of `coins` units covers at `strike` (as the desk rounds: down) */
+export const coverOf = (coins, strike) => (coins * strike) / 10n ** 18n;
+/** coin units whose cover is `coverWei` at `strike` (rounded down) */
+export const coinsFor = (coverWei, strike) => (strike > 0n ? (coverWei * 10n ** 18n) / strike : 0n);
+export function dipsModule(ctx) {
+    const { pub, a } = ctx;
+    const D = dipDeskAbi;
+    const desk = a.dipsDesk;
+    const call = (functionName, args = []) => pub.readContract({ address: desk, abi: D, functionName, args });
+    const now = async () => Number((await pub.getBlock({ blockTag: "latest" })).timestamp);
+    const toBid = (id, b, t) => ({
+        id,
+        maker: b.maker,
+        token: b.token,
+        strike: b.strike,
+        duration: Number(b.duration),
+        premiumBps: Number(b.premiumBps),
+        until: Number(b.until),
+        closed: b.closed,
+        minCover: b.minCover,
+        free: b.free,
+        locked: b.locked,
+        live: !b.closed && Number(b.until) > t && b.free >= b.minCover,
+    });
+    /** The desk's fees and limits. */
+    async function terms() {
+        const fns = ["premiumFeeBps", "exerciseFeeBps", "MIN_DEPOSIT", "MIN_COVER", "MIN_DURATION", "MAX_DURATION", "MAX_PREMIUM_BPS"];
+        const r = await pub.multicall({ contracts: fns.map((functionName) => ({ address: desk, abi: D, functionName })), allowFailure: false });
+        return { premiumFeeBps: Number(r[0]), exerciseFeeBps: Number(r[1]), minDeposit: r[2], minCover: r[3], minDuration: Number(r[4]), maxDuration: Number(r[5]), maxPremiumBps: Number(r[6]) };
+    }
+    /** The newest bids on a coin (up to `limit`), with whether each takes a floor now. */
+    async function bids(token, o = {}) {
+        const [r, t] = await Promise.all([call("bidsOf", [token, BigInt(o.limit ?? 200)]), now()]);
+        return r[0].map((id, i) => toBid(id, r[1][i], t));
+    }
+    async function bid(id) {
+        const [b, t] = await Promise.all([call("bidOf", [id]), now()]);
+        if (/^0x0{40}$/i.test(b.maker))
+            throw new PickhooksError("There is no bid with this id.", { code: "NoBid" });
+        return toBid(id, b, t);
+    }
+    /** A holder's floors (still holding coins), newest last. */
+    async function floorsOf(holder) {
+        const [ids] = await call("floorIdsOf", [holder, 0n, 1000n]);
+        if (!ids.length)
+            return [];
+        const r = await pub.multicall({ contracts: ids.map((id) => ({ address: desk, abi: D, functionName: "floorOf", args: [id] })), allowFailure: true });
+        const out = [];
+        r.forEach((x, i) => {
+            if (x.status !== "success")
+                return;
+            const f = x.result;
+            if (f.coins === 0n || f.owner.toLowerCase() !== holder.toLowerCase())
+                return;
+            out.push({ id: ids[i], bid: f.bid, owner: f.owner, coins: f.coins, cover: f.cover, premium: f.premium, bought: Number(f.bought), expiry: Number(f.expiry), feeBps: Number(f.feeBps) });
+        });
+        return out;
+    }
+    /** What a floor of `coins` on a bid covers, costs (premium, the desk's fee in it) and pays the maker. */
+    async function quote(bidId, coins) {
+        try {
+            const [cover, premium, fee, payout] = await call("quote", [bidId, coins]);
+            return { cover, premium, fee, payout };
+        }
+        catch (e) {
+            throw toPickhooksError(e, "The desk refused this floor.");
+        }
+    }
+    /** What handing in `coins` of a floor would pay `owner` now (the coins must be there and approved), or the refusal. */
+    async function dryExercise(floorId, coins, owner) {
+        try {
+            const r = await pub.simulateContract({ address: desk, abi: D, functionName: "exercise", args: [floorId, coins, 0n], account: owner });
+            return { ok: true, out: r.result };
+        }
+        catch (e) {
+            return { ok: false, why: toPickhooksError(e, "The coin refused the hand in.").message };
+        }
+    }
+    const tx = (fn, args = [], value = 0n, label) => ({ to: desk, value, data: encodeFunctionData({ abi: D, functionName: fn, args }), label });
+    const build = {
+        post: (p) => tx("post", [p.token, p.strike ?? strikeFromPrice(p.price ?? 0), p.duration, p.premiumBps, p.until, p.minCover], p.deposit, "Posting the bid"),
+        fund: (id, wei) => tx("fund", [id], wei, "Funding the bid"),
+        withdraw: (id, wei) => tx("withdraw", [id, wei], 0n, "Taking free BNB back"),
+        close: (id) => tx("close", [id], 0n, "Closing the bid"),
+        /** value = the quoted premium */
+        buyFloor: (bidId, coins, premium) => tx("buy", [bidId, coins], premium, "Buying the floor"),
+        /** needs the coin approved to the desk */
+        exercise: (floorId, coins, minBnb) => tx("exercise", [floorId, coins, minBnb], 0n, "Handing coins in"),
+        end: (floorId) => tx("end", [floorId], 0n, "Ending the floor"),
+        give: (floorId, to) => tx("give", [floorId, to], 0n, "Giving the floor away"),
+        withdrawPending: () => tx("withdrawPending", [], 0n, "Taking pending BNB"),
+    };
+    const idFrom = (sent, eventName) => parseEventLogs({ abi: D, logs: sent.receipt.logs.filter((l) => l.address.toLowerCase() === desk.toLowerCase()) }).find((e) => e.eventName === eventName)?.args.id ?? 0n;
+    return {
+        desk,
+        terms,
+        bids,
+        bid,
+        floorsOf,
+        quote,
+        dryExercise,
+        pending: (who) => call("pending", [who]),
+        strikeFromPrice,
+        coverOf,
+        coinsFor,
+        build,
+        /** posts a bid with its deposit; returns the bid id */
+        post: async (p, s = {}) => {
+            const sent = await sendTx(ctx, build.post(p), s);
+            return { ...sent, id: idFrom(sent, "BidPosted") };
+        },
+        fund: (id, wei, s = {}) => sendTx(ctx, build.fund(id, wei), s),
+        withdraw: (id, wei, s = {}) => sendTx(ctx, build.withdraw(id, wei), s),
+        close: (id, s = {}) => sendTx(ctx, build.close(id), s),
+        /** pays exactly the quoted premium; returns the floor id */
+        buyFloor: async (bidId, coins, s = {}) => {
+            const q = await quote(bidId, coins);
+            const sent = await sendTx(ctx, build.buyFloor(bidId, coins, q.premium), s);
+            return { ...sent, id: idFrom(sent, "FloorBought"), premium: q.premium };
+        },
+        /** approves the coin to the desk if needed, then hands `coins` in for at least the dry run's payout less slippageBps */
+        exercise: async (o, s = {}) => {
+            const { address } = await signer(ctx, s.wallet);
+            const ap = await approvalFor(ctx, address, o.token, o.coins, desk, "Allowing the desk");
+            if (ap)
+                await sendTx(ctx, ap, s);
+            const dry = await dryExercise(o.floorId, o.coins, address);
+            if (!dry.ok)
+                throw new PickhooksError(dry.why, { code: "dips" });
+            const sent = await sendTx(ctx, build.exercise(o.floorId, o.coins, minusBps(dry.out, o.slippageBps ?? 100)), s);
+            return { ...sent, paid: dry.out };
+        },
+        end: (floorId, s = {}) => sendTx(ctx, build.end(floorId), s),
+        give: (floorId, to, s = {}) => sendTx(ctx, build.give(floorId, to), s),
+        withdrawPending: (s = {}) => sendTx(ctx, build.withdrawPending(), s),
+    };
+}

package/dist/errors.d.ts

@@ -0,0 +1,35 @@
+import { type Hex } from "viem";
+/** What hook any coin's factory.check() answers, in words. */
+export declare const CHECK_TEXT: Record<number, string>;
+/** An error of the SDK: `code` is the contract's error name (or "wallet", "reverted", "input"), `text` a sentence. */
+export declare class PickhooksError extends Error {
+    readonly code: string;
+    readonly args?: readonly unknown[];
+    readonly hash?: Hex;
+    constructor(text: string, opts: {
+        code: string;
+        args?: readonly unknown[];
+        hash?: Hex;
+        cause?: unknown;
+    });
+}
+/** The revert data inside a viem error (it nests them), or null. */
+export declare function findRevertData(err: unknown): Hex | null;
+/** A decoded contract error, searched at the start of the revert data and, for wrapped errors, anywhere inside it. */
+export declare function decodeRevert(data: Hex): {
+    name: string;
+    args: readonly unknown[];
+} | null;
+/** A contract error as a sentence. */
+export declare function errorText(name: string, args: readonly unknown[]): string;
+/**
+ * Any error as a code and a sentence: a wallet refusal, a pickhooks contract's error (wrapped by PancakeSwap or not), one
+ * of PancakeSwap's trade errors, or the fallback.
+ */
+export declare function explain(err: unknown, fallback?: string): {
+    code: string;
+    text: string;
+    args?: readonly unknown[];
+};
+/** Wraps any error as a PickhooksError (keeps the original as `cause`). */
+export declare function toPickhooksError(err: unknown, fallback?: string, hash?: Hex): PickhooksError;

package/dist/errors.js

@@ -0,0 +1,347 @@
+import { decodeErrorResult, toFunctionSelector } from "viem";
+import { formatAbiItem } from "viem/utils";
+import { any3FactoryAbi, any3HookAbi } from "./abis/any3.js";
+import { anyTaxFactoryAbi, anyTaxHookAbi } from "./abis/anytax.js";
+import { callsDeskAbi, callsFactoryAbi, callsHookAbi } from "./abis/calls.js";
+import { dipDeskAbi } from "./abis/dips.js";
+import { hooksExecutorAbi, hooksFloorAbi, hooksFloorFactoryAbi } from "./abis/infra.js";
+import { leverEngineAbi, leverFactoryAbi, leverHookAbi, leverRouterAbi } from "./abis/lever.js";
+import { lever2EngineAbi, lever2FactoryAbi, lever2HookAbi } from "./abis/lever2.js";
+import { poolsFactoryAbi, poolsHookAbi } from "./abis/pools.js";
+import { stickyFactoryAbi, stickyTokenAbi, stickyValidatorAbi } from "./abis/sticky.js";
+import { v1FactoryAbi, v1TokenAbi } from "./abis/v1.js";
+import { arenaAbi, floorVaultAbi, payrollBoxAbi, v2FactoryAbi, v2TokenAbi, voteBoxAbi } from "./abis/v2.js";
+/** sticky: what token.check() answers when no row stops a trade but the coins are not unlocked yet */
+const STICKY_LOCKED = 254;
+/** What hook any coin's factory.check() answers, in words. */
+export const CHECK_TEXT = {
+    0: "This coin can get a pickhooks pool.",
+    1: "There is no contract at this address.",
+    2: "BNB and stablecoins are the other side of a pool, not a coin to hook.",
+    3: "This coin is still on its launch curve. Once it trades on PancakeSwap it can get a pool.",
+    4: "This coin has a transfer tax. A pool here would be a way around it, so it gets none.",
+    5: "This coin pays dividends to holders. The pool would count as a holder, so it gets none.",
+    6: "No PancakeSwap pool of this coin against BNB holds at least 3 BNB, so there is no fair price to open at.",
+};
+/** hook any coin's factory and sticky's factory and validator: Bad(what) as a sentence */
+const BAD = {
+    // hook any coin, open()
+    fee: "Pool fee: 0.2 to 1 % (feeBps 20 to 100).",
+    holderFee: "The holder fee cannot be higher than the pool fee.",
+    chest: "The fire: at most 10 % of a buy (chestBps up to 1000).",
+    bonus: "Bonus: at most 10 % (bonusBps up to 1000).",
+    bonusLock: "Bonus lock: 1 to 30 days.",
+    jackpotShare: "Jackpot share: 1 to 100 % of the pot (jackpotShareBps 100 to 10000).",
+    jackpotMinBuy: "Jackpot minimum buy: at most 10 BNB.",
+    silence: "Jackpot silence: 1 minute to 7 days.",
+    potShare: "Jackpot: potShareBps at most 10000.",
+    "no opener side for a pot": "A jackpot needs an opener side to fill it.",
+    maxMove: "maxMoveBps: at most 500 (5 %).",
+    slot: "That slot is out of range or taken. Check the coin again for a free slot.",
+    ticks: "The range is not valid for this slot.",
+    liquidity: "Put in coins (and BNB for a range around the price).",
+    partner: "That partner is not listed by pickhooks.",
+    "no pool": "There is no pool with this id.",
+    openerBps: "openerBps out of range.",
+    traderBps: "traderBps out of range.",
+    // sticky
+    seed: "The seed is out of range.",
+    creatorBps: "creatorBps out of range.",
+    startFdv: "startFdv out of range.",
+    "two sided": "The pool would be two sided.",
+    rows: "At most eight rows.",
+    "not a template": "Only the launcher's templates can launch right now (hook script is off).",
+    burn: "Auto burn: at most 10 % in total.",
+    release: "The unlock time must be 10 minutes to 30 days.",
+    age: "Hold time: at most 7 days.",
+    window: "Sell window: open at least a minute, the period at most a day.",
+    hour: "Market hours: whole hours from 1 to 23.",
+    terms: "The fee terms changed since they were read. Read them again.",
+    keep: "keepBps: at most 10000.",
+    value: "Send at least the seed.",
+    metadata: "The metadata link is too long.",
+    name: "Name or ticker too long.",
+    "sell deny must end": "A rule that stops sells or sends must let go by itself.",
+    windows: "One sell window at most, and not next to rows on hours or weekdays.",
+    hours: "The rows on hours close every hour of the day: leave one open.",
+    weekdays: "The rows on weekdays close every day: leave one open.",
+    take: "Burn and pot: at most 10 % of a buy together.",
+    pot: "Pot: 0.01 to 10 % of the buy.",
+    drop: "Drop: 0.01 to 100 % of the pot.",
+    "pot needs a drop": "A pot needs a drop row that pays it out.",
+    every: "Every n-th buy: n from 2 to 1,000,000.",
+    idle: "Time since the last buy: at most 30 days.",
+};
+/** every other error of the pickhooks contracts, by name */
+const BY_NAME = {
+    // hook any coin, factory
+    NotOwner: "Only the factory's owner can do that.",
+    NotOpener: "Only the opener of this pool can do that.",
+    NoLiquidity: "That is too little to add any liquidity. Put in more.",
+    FeeOnTransfer: "This coin takes a fee on transfers, so it cannot go into a pool.",
+    Transfer: "The coin refused the transfer. Check the balance and the allowance.",
+    PriceMoved: "The coin's price moved more than allowed while the pool opened. Check again and open.",
+    TooShallow: "Not enough liquidity: the pool must be at least as deep as the coin's main pool.",
+    StillLocked: "This position is still locked. Each one stays 30 days after it went in.",
+    NoPosition: "That position is already out.",
+    TooMany: "A pool holds at most 8 positions.",
+    InvalidTick: "The range is not on the pool's tick spacing.",
+    // hook any coin, hook
+    UnknownPool: "There is no pickhooks pool with this id.",
+    NoPot: "This pool has no jackpot.",
+    NoBonus: "This pool has no bonus rule.",
+    NothingOwed: "Nothing to claim yet.",
+    NotBought: "Only coins bought in this pool can be locked, and no more than that.",
+    NoBonusLeft: "The bonus pot has nothing left for this wallet: it is empty, or the cap is reached.",
+    Locked: "The bonus is still locked.",
+    Reentry: "A call came back into the hook while it was busy.",
+    Pending: "A router still has a payment open in the vault.",
+    // sticky and the coins with rules
+    PoolPrice: "Someone opened this coin's pool first. Launch again (a new salt).",
+    NotCreator: "Only the coin's creator can do that.",
+    Nope: "The coin refused this.",
+    // hook any coin, tax line
+    PayFirst: "While this coin's anti-farmer tax runs, a sell in this pool must pay its coins in first (the SDK's sell does). Terminals sell it in its main pool.",
+    // pools, Lever
+    PartialFill: "The trade would not fill completely. Try a smaller amount.",
+    SwapNotFilled: "The trade would not fill completely. Try a smaller amount.",
+    // lever and Lever
+    MarginTooSmall: "The smallest position is 0.01 BNB of margin plus the open fee.",
+    InvalidLeverage: "Up to 3x in a coin's first 10 minutes, then up to 5x.",
+    TooManyPositions: "All position slots of this coin are taken. A bigger margin takes the smallest one's slot (Lever), or wait until one closes.",
+    OpenInterestLimit: "Longs are full for now: all longs together may borrow at most a quarter of the real BNB in the curve.",
+    LongsFull: "Longs are full for now: all longs together may borrow at most a quarter of the real BNB in the curve. Try a smaller position or wait for more buys.",
+    ShortsFull: "Shorts are full for now: all shorts together may sell coins for at most a quarter of the real BNB in the curve. Try a smaller position or wait for more buys.",
+    UnsafePosition: "This position would sit right at its liquidation point. Try a smaller one or a lower leverage.",
+    Unsafe: "This trade would leave a position at its liquidation point. Try a smaller margin or a lower leverage.",
+    BandFull: "The curve cannot lend that much right now. Try a smaller position.",
+    BadDebt: "This position cannot cover what it borrowed at this price. The next trade that reaches it liquidates it.",
+    Pushed: "The price was pushed in this second. Try again in a moment.",
+    TooSoon: "A position cannot be closed in the second it opened. Try again in a moment.",
+    Slippage: "The price moved past the limit while the transaction waited. Try again.",
+    Expired: "The transaction waited too long. Try again.",
+    InsufficientTokens: "That is more coins than this wallet holds.",
+    InsufficientCash: "The curve does not hold that much BNB.",
+    ZeroAmount: "That amount is too small to trade.",
+    UnsupportedSwap: "That amount is too small to trade.",
+    BadAmount: "That amount is too small to trade.",
+    ReserveLimit: "That amount is too big for the curve.",
+    AmountTooLarge: "That amount is too big for the curve.",
+    InactivePosition: "That position is already closed.",
+    NotExpired: "This has not run out yet: only its owner can close it now.",
+    UnknownMarket: "This is not a lever coin.",
+    InvalidMarket: "This is not a lever coin.",
+    NoLiquidityPositions: "Only the coin's curve can hold liquidity in this pool.",
+    Unauthorized: "This contract only takes that call from its own router or hook.",
+    // curve calls
+    TooEarly: "Calls open 10 minutes after the launch, and an owner can close a call 10 minutes after it opened.",
+    NotAbove: "That step is not fully above the price any more. Pick a step further up.",
+    TooFar: "A call can be at most 8 steps above the price.",
+    OverCap: "That is more than the step has left to rent: at most 10 % of a step is out at once.",
+    SameBlock: "Someone opened a call on this coin in the same block. Try again.",
+    PremiumTooHigh: "The premium went up since the quote. Try again.",
+    Paused: "PancakeSwap has paused its pools. Calls open again when it resumes.",
+    OffAverage: "The price is far from its 10 minute average right now. Anyone can close an ended call once it settles, or an hour after the end.",
+    NoCall: "That call is already closed.",
+    NothingPending: "Nothing waits for this wallet here.",
+    // curve calls and dip bids
+    TooSmall: "That is too small: below the smallest call or floor.",
+    Duration: "That duration is out of range (calls 10 minutes to 24 hours, floors 10 minutes to 7 days).",
+    Value: "The BNB sent does not match. Quote again.",
+    PayoutTooLow: "The payout fell below the minimum while the transaction waited. Try again.",
+    // dip bids
+    NoCoin: "That is not a coin contract.",
+    Strike: "Set a price for the bid.",
+    Premium: "The premium is between 0.01 % and 50 % of what a floor covers.",
+    Until: "The end of the bid has to be in the future.",
+    Deposit: "A new bid locks at least 0.01 BNB, and at least its smallest floor.",
+    IsClosed: "That bid is closed.",
+    BidOver: "That bid has ended: it takes no new floors.",
+    TooBig: "The bid has less BNB free than this floor covers. Protect fewer coins or pick another bid.",
+    Ended: "That floor has run out or was already handed in.",
+    NotOver: "Only the owner can end a floor before it runs out.",
+    NotYours: "That floor belongs to another wallet.",
+    NotMaker: "Only the wallet that posted the bid can do that.",
+    Delivery: "The coins could not be handed in: check that this wallet holds them and has approved the desk.",
+    NoBid: "There is no bid with this id.",
+    NoFloor: "There is no floor with this id.",
+    Reentrant: "The desk is busy. Try again.",
+    // HOOKS infra: floors and the protected buy
+    SupplyGrew: "The coin minted new coins since its floor opened, so the floor takes no more hand ins.",
+    Exists: "This coin already has a floor. Feed it instead.",
+    Amount: "Hand in more than zero coins.",
+    SendFailed: "The BNB could not be sent to that address.",
+    TooFewCoins: "The swap brought fewer coins than the minimum. Quote again or allow more slippage.",
+    WrongCoin: "The dip bid is for another coin.",
+    NothingToProtect: "No coins arrived to protect.",
+    Swap: "The swap through PancakeSwap failed.",
+    Target: "The executor only calls PancakeSwap's own routers.",
+};
+/** PancakeSwap's own errors that a trade can run into */
+const PANCAKE = [
+    ["0x5bf6f916", "The trade waited too long and ran out of time (deadline). Try again."],
+    [toFunctionSelector("TooLittleReceived(uint256,uint256)"), "The price moved: the trade would get less than the minimum. Quote again or allow more slippage."],
+    [toFunctionSelector("V3TooLittleReceived()"), "The price moved: the trade would get less than the minimum. Quote again or allow more slippage."],
+    [toFunctionSelector("InsufficientToken()"), "The trade got less than the minimum. Quote again or allow more slippage."],
+    ["0xd964f528", "The pool could not fill the whole amount. Try a smaller one."],
+];
+/** The pickhooks contracts' ABIs that errors are decoded with. */
+const ABIS = [
+    any3FactoryAbi,
+    any3HookAbi,
+    stickyFactoryAbi,
+    stickyValidatorAbi,
+    stickyTokenAbi,
+    anyTaxFactoryAbi,
+    anyTaxHookAbi,
+    v1FactoryAbi,
+    v1TokenAbi,
+    v2FactoryAbi,
+    v2TokenAbi,
+    voteBoxAbi,
+    arenaAbi,
+    floorVaultAbi,
+    payrollBoxAbi,
+    poolsFactoryAbi,
+    poolsHookAbi,
+    leverFactoryAbi,
+    leverHookAbi,
+    leverEngineAbi,
+    leverRouterAbi,
+    lever2FactoryAbi,
+    lever2HookAbi,
+    lever2EngineAbi,
+    callsFactoryAbi,
+    callsHookAbi,
+    callsDeskAbi,
+    dipDeskAbi,
+    hooksExecutorAbi,
+    hooksFloorAbi,
+    hooksFloorFactoryAbi,
+];
+/** every error selector the pickhooks ABIs know, for errors that PancakeSwap wraps (WrappedError, the quoter's revert) */
+const SELECTORS = ABIS.flatMap((abi) => abi.filter((x) => x.type === "error").map((x) => ({ sel: toFunctionSelector(formatAbiItem(x)).slice(2).toLowerCase(), abi })));
+/** An error of the SDK: `code` is the contract's error name (or "wallet", "reverted", "input"), `text` a sentence. */
+export class PickhooksError extends Error {
+    code;
+    args;
+    hash;
+    constructor(text, opts) {
+        super(text, { cause: opts.cause });
+        this.name = "PickhooksError";
+        this.code = opts.code;
+        this.args = opts.args;
+        this.hash = opts.hash;
+    }
+}
+/** The revert data inside a viem error (it nests them), or null. */
+export function findRevertData(err) {
+    let e = err;
+    for (let i = 0; i < 10 && e; i++) {
+        if (typeof e.data === "string" && e.data.startsWith("0x") && e.data.length >= 10)
+            return e.data;
+        if (e.data && typeof e.data.data === "string")
+            return e.data.data;
+        e = e.cause;
+    }
+    const m = String(err?.message ?? "").match(/0x[0-9a-f]{8,}/i);
+    return m ? m[0] : null;
+}
+/** A decoded contract error, searched at the start of the revert data and, for wrapped errors, anywhere inside it. */
+export function decodeRevert(data) {
+    for (const abi of ABIS) {
+        try {
+            const d = decodeErrorResult({ abi, data });
+            return { name: d.errorName, args: (d.args ?? []) };
+        }
+        catch {
+            /* not this contract's error */
+        }
+    }
+    const hex = data.toLowerCase().slice(2);
+    // a wrapped error carries the inner revert as bytes: find a known selector on a byte boundary and decode from there
+    for (const { sel, abi } of SELECTORS) {
+        let i = hex.indexOf(sel);
+        while (i >= 0) {
+            if (i % 2 === 0) {
+                try {
+                    const d = decodeErrorResult({ abi, data: `0x${hex.slice(i)}` });
+                    return { name: d.errorName, args: (d.args ?? []) };
+                }
+                catch {
+                    /* trailing bytes of the wrapper: try the selector with its own words only */
+                    try {
+                        const d = decodeErrorResult({ abi, data: `0x${hex.slice(i, i + 8 + 64 * 8)}` });
+                        return { name: d.errorName, args: (d.args ?? []) };
+                    }
+                    catch {
+                        /* keep looking */
+                    }
+                }
+            }
+            i = hex.indexOf(sel, i + 1);
+        }
+    }
+    return null;
+}
+/** require() strings of PancakeSwap's V3 contracts that need a sentence */
+const ERROR_STRING = {
+    "Unexpected error": "PancakeSwap's quoter could not run this trade: the coin refused it, and the quoter does not pass the reason on.",
+    "Transaction too old": "The trade's deadline passed before it was mined. Send it again.",
+    "Too little received": "The price moved more than the slippage allows. Quote again or allow more slippage.",
+    SPL: "The trade would move the price past its limit.",
+};
+/** A contract error as a sentence. */
+export function errorText(name, args) {
+    if (name === "Error")
+        return ERROR_STRING[String(args[0])] ?? `The contract refused: ${String(args[0] ?? "")}`;
+    if (name === "Panic")
+        return `The contract stopped with panic code ${String(args[0] ?? "")}.`;
+    if (name === "Refused")
+        return CHECK_TEXT[Number(args[0])] ?? "The factory refused this coin.";
+    if (name === "Blocked") {
+        const row = Number(args[0]);
+        return row === STICKY_LOCKED ? "Those coins are still locked: they unlock over time." : `Refused by rule ${row + 1} of the coin.`;
+    }
+    if (name === "Bad") {
+        const what = String(args[0] ?? "");
+        if (!what)
+            return "The hook refused these numbers.";
+        return BAD[what] ?? `Refused: ${what}.`;
+    }
+    return BY_NAME[name] ?? `The contract refused (${name}).`;
+}
+/**
+ * Any error as a code and a sentence: a wallet refusal, a pickhooks contract's error (wrapped by PancakeSwap or not), one
+ * of PancakeSwap's trade errors, or the fallback.
+ */
+export function explain(err, fallback = "The transaction would fail.") {
+    if (err instanceof PickhooksError)
+        return { code: err.code, text: err.message, args: err.args };
+    const msg = String(err?.message ?? "");
+    if (/user rejected|denied transaction|rejected the request|\b4001\b/i.test(msg))
+        return { code: "wallet", text: "Cancelled in the wallet. Nothing was sent." };
+    if (/insufficient funds/i.test(msg))
+        return { code: "funds", text: "Not enough BNB in this wallet for the amount plus gas." };
+    const data = findRevertData(err);
+    if (data) {
+        const d = decodeRevert(data);
+        if (d)
+            return { code: d.name, text: errorText(d.name, d.args), args: d.args };
+        const low = data.toLowerCase();
+        for (const [sel, text] of PANCAKE)
+            if (low.includes(sel.slice(2).toLowerCase()))
+                return { code: "pancake", text };
+    }
+    const reason = msg.match(/reverted with the following reason:\s*\n?\s*(.+)/);
+    if (reason)
+        return { code: "reverted", text: `The contract refused: ${reason[1].trim()}` };
+    return { code: "unknown", text: fallback };
+}
+/** Wraps any error as a PickhooksError (keeps the original as `cause`). */
+export function toPickhooksError(err, fallback, hash) {
+    if (err instanceof PickhooksError)
+        return err;
+    const e = explain(err, fallback);
+    return new PickhooksError(e.text, { code: e.code, args: e.args, hash, cause: err });
+}

package/dist/index.d.ts

@@ -0,0 +1,73 @@
+import type { PublicClient } from "viem";
+import type { Addresses } from "./addresses.js";
+import { type AnyModule } from "./any.js";
+import { type ApiModule } from "./api.js";
+import { type Block, type BlocksCatalog } from "./blocks.js";
+import { type CoinsModule } from "./coins.js";
+import { type DipsModule } from "./dips.js";
+import { type InfraModule } from "./infra.js";
+import { type Lever2Module, type LeverModule } from "./lever.js";
+import { type CallsModule, type PoolsModule } from "./pools.js";
+import { type StickyModule } from "./sticky.js";
+import { type PickhooksOptions, type SendOptions, type Sent, type TxRequest } from "./tx.js";
+export type Pickhooks = {
+    addresses: Addresses;
+    publicClient: PublicClient;
+    /** hook any coin: pools next to coins that already trade (v3 with recapture, partners, routers; the tax line when set) */
+    any: AnyModule;
+    /** sticky rules: rules that stick to the coins */
+    sticky: StickyModule;
+    /** coins with their rules in the coin (v1 and v2, also find the dev and CZ mode coins) */
+    coins: CoinsModule;
+    /** pools: coins with their rules in a PancakeSwap Infinity pool hook */
+    pools: PoolsModule;
+    /** curve calls: rent a step of a coin's curve */
+    calls: CallsModule;
+    /** Lever (v2): real liquidity, longs and shorts */
+    lever: Lever2Module;
+    /** lever (v1): the engine curve with longs */
+    leverV1: LeverModule;
+    /** dip bids: floors at a strike */
+    dips: DipsModule;
+    /** HOOKS infra: BNB floors under coins and the protected buy (off while their addresses are zero) */
+    infra: InfraModule;
+    /** the building blocks: sticky rules' ready blocks with their numbers and rows, the hook script grammar, the rule book (offline; ph.api.blocks() asks the site) */
+    blocks: {
+        catalog: () => BlocksCatalog;
+        block: (id: string) => Block | null;
+    };
+    /** pickhooks.com's public JSON API */
+    api: ApiModule;
+    /** sends any TxRequest the build helpers return (estimate x gasPct + its extraGas) and waits for the receipt */
+    send: (tx: TxRequest, o?: SendOptions) => Promise<Sent>;
+    sendAll: (txs: TxRequest[], o?: SendOptions) => Promise<Sent[]>;
+};
+/**
+ * The pickhooks SDK. One client, a part per product:
+ *   any      hook any coin: quotes, trades with the recapture room, opening a pool with a partner, the payouts
+ *   sticky   sticky rules: launching from templates, checking a trade against the coin's table, trading, lifting
+ *   coins    coins with rules in the coin (v1, v2): rules as sentences, the rule that would refuse a trade, launches
+ *   pools    rules in the pool; calls: curve calls; lever: Lever longs and shorts (leverV1 the first lever); dips: dip bids
+ *   api      pickhooks.com's public JSON API (launch feed, board, activity)
+ *
+ *   const ph = createPickhooks({ walletClient });
+ *   const [pool] = await ph.any.pools({ limit: 1 });
+ *   const r = await ph.any.buy({ pool, bnbIn: parseEther("0.05") });
+ */
+export declare function createPickhooks(options?: PickhooksOptions): Pickhooks;
+export { BSC_MAINNET, LIMITS, NATIVE, ZERO_ADDRESS, type Addresses } from "./addresses.js";
+export { CHECK_TEXT, PickhooksError, decodeRevert, errorText, explain, findRevertData } from "./errors.js";
+export { DEFAULT_RPC, deadlineIn, minusBps, type PickhooksOptions, type SendOptions, type Sent, type TxRequest } from "./tx.js";
+export { blockedKind, buildInfiSwap, infiPriceBnb, infiQuote, infiSwapInput, permit2Approvals, poolIdOf, toKey, type PoolKey } from "./infinity.js";
+export { approvalFor, buildV3Buy, buildV3Sell, receivedOf, v3PriceBnb, v3Quote } from "./v3.js";
+export { MAX_TICK, MIN_TICK, TAX_QUOTE_MARK, afterTax, depthNeeds, fitLadder, partnerLink, rangeFor, tickOf, type AnyLine, type AnyModule, type AnyPool, type AnyQuote, type CoinCheck, type Earnings, type OpenOptions, type OpenParams, type PoolConfig, type PoolPosition, type PoolRef, type RangeKind, type Recapture, type TaxLive, type TradeResult, } from "./any.js";
+export { describeRows, type StickyCheck, type StickyCoin, type StickyLaunch, type StickyLot, type StickyModule, type StickyRow, type StickyTerms, } from "./sticky.js";
+export { ruleText, type CoinRule, type CoinsModule, type RuleCheck, type RuleCoin, type RuleCoinVersion, type RuleLaunch } from "./coins.js";
+export { type CallRow, type CallStep, type CallsModule, type HookCoin, type HookLaunch, type PoolsModule } from "./pools.js";
+export { LEVER2_REASON, type Lever2CloseQuote, type Lever2Module, type Lever2OpenQuote, type Lever2Row, type Lever2State, type LeverCoin, type LeverMarket, type LeverModule, type LeverPosition, } from "./lever.js";
+export { coinsFor, coverOf, strikeFromPrice, type DipBid, type DipFloor, type DipPost, type DipsModule } from "./dips.js";
+export { type ApiModule, type Launch, type LaunchFeed } from "./api.js";
+export { type FloorState, type InfraModule, type ProtectOffer } from "./infra.js";
+export { BLOCKS_VERSION, BLOCK_ACTIONS, BLOCK_CHECKS, BLOCK_MARKS, BLOCK_OPERATORS, BLOCK_TRIGGERS, blockLineVars, blocksCatalog, type Block, type BlockAction, type BlockParam, type BlockVariable, type BlocksCatalog, type CoinRuleBlock, type CoinRuleField, type GrammarItem, } from "./blocks.js";
+export { ACT, FLAG, LOCKED, NONE, ON, OP, STICKY_LIMITS, TEMPLATES, TEMPLATE_BY_ID, VAR, VARS, VAR_BY_ID, compile, decodeRow, defaults, editToRow, emptyEditRow, encodeRow, paramProblems, rowProblems, rowText, scannerOf, tableProblems, templateOf, type Cond, type EditCond, type EditRow, type Pick, type Row, type Template, type TemplateId, } from "./sticky-rules.js";
+export { GROUPS, RULES, RULE_BY_ID, RULE_BY_KIND, buildRules, emptyExtras, emptyRules, fieldProblem, kindsOf, refusal, selectionProblem, v2Costs, worstScanner, defaults as ruleDefaults, type Picked, type R as CoinRules, type RuleDef, type X as CoinExtras, } from "./coin-rules.js";