@pickhooks/sdk 0.0.0-stage → 0.4.0

package/dist/dips.d.ts

@@ -0,0 +1,133 @@
+import { type Address } from "viem";
+import { type Ctx, type SendOptions, type Sent, type TxRequest } from "./tx.js";
+/**
+ * Dip bids (desk 0xc73b…65bf, one desk for every coin, no oracle, no pool touched): a dip buyer locks BNB at their price
+ * (the strike) and names a premium; a holder pays that premium for a floor, the right to hand coins in at the strike
+ * until it runs out. Pump: the holder keeps the coins. Dump: the coins go to the dip buyer, the holder takes the BNB.
+ * Prices: a strike is BNB wei per whole coin (1e18 units).
+ */
+export type DipBid = {
+    id: bigint;
+    maker: Address;
+    token: Address;
+    /** BNB wei per whole coin */
+    strike: bigint;
+    /** how long a floor bought on it runs, seconds */
+    duration: number;
+    premiumBps: number;
+    /** the bid takes new floors until then */
+    until: number;
+    closed: boolean;
+    /** the smallest floor's cover, BNB wei */
+    minCover: bigint;
+    /** BNB free for new floors, and BNB locked for floors bought */
+    free: bigint;
+    locked: bigint;
+    /** it takes a new floor now */
+    live: boolean;
+};
+export type DipFloor = {
+    id: bigint;
+    bid: bigint;
+    owner: Address;
+    coins: bigint;
+    cover: bigint;
+    premium: bigint;
+    bought: number;
+    expiry: number;
+    feeBps: number;
+};
+export type DipPost = {
+    token: Address;
+    /** BNB per coin (a number), or `strike` in BNB wei per whole coin */
+    price?: number;
+    strike?: bigint;
+    /** seconds a floor runs: 10 minutes to 7 days */
+    duration: number;
+    /** what a floor costs, basis points of what it covers (up to 50 %) */
+    premiumBps: number;
+    /** unix time the bid stops taking floors */
+    until: number;
+    /** the smallest floor, BNB wei of cover (at least the desk's MIN_COVER) */
+    minCover: bigint;
+    /** BNB the bid locks (at least the desk's MIN_DEPOSIT and its smallest floor) */
+    deposit: bigint;
+};
+/** strike = BNB wei per whole coin, from a price in BNB per coin */
+export declare function strikeFromPrice(priceBnb: number): bigint;
+/** BNB wei a floor of `coins` units covers at `strike` (as the desk rounds: down) */
+export declare const coverOf: (coins: bigint, strike: bigint) => bigint;
+/** coin units whose cover is `coverWei` at `strike` (rounded down) */
+export declare const coinsFor: (coverWei: bigint, strike: bigint) => bigint;
+export declare function dipsModule(ctx: Ctx): {
+    desk: `0x${string}`;
+    terms: () => Promise<{
+        premiumFeeBps: number;
+        exerciseFeeBps: number;
+        minDeposit: bigint;
+        minCover: bigint;
+        minDuration: number;
+        maxDuration: number;
+        maxPremiumBps: number;
+    }>;
+    bids: (token: Address, o?: {
+        limit?: number;
+    }) => Promise<DipBid[]>;
+    bid: (id: bigint) => Promise<DipBid>;
+    floorsOf: (holder: Address) => Promise<DipFloor[]>;
+    quote: (bidId: bigint, coins: bigint) => Promise<{
+        cover: bigint;
+        premium: bigint;
+        fee: bigint;
+        payout: bigint;
+    }>;
+    dryExercise: (floorId: bigint, coins: bigint, owner: Address) => Promise<{
+        ok: true;
+        out: bigint;
+    } | {
+        ok: false;
+        why: string;
+    }>;
+    pending: (who: Address) => Promise<bigint>;
+    strikeFromPrice: typeof strikeFromPrice;
+    coverOf: (coins: bigint, strike: bigint) => bigint;
+    coinsFor: (coverWei: bigint, strike: bigint) => bigint;
+    build: {
+        post: (p: DipPost) => TxRequest;
+        fund: (id: bigint, wei: bigint) => TxRequest;
+        withdraw: (id: bigint, wei: bigint) => TxRequest;
+        close: (id: bigint) => TxRequest;
+        /** value = the quoted premium */
+        buyFloor: (bidId: bigint, coins: bigint, premium: bigint) => TxRequest;
+        /** needs the coin approved to the desk */
+        exercise: (floorId: bigint, coins: bigint, minBnb: bigint) => TxRequest;
+        end: (floorId: bigint) => TxRequest;
+        give: (floorId: bigint, to: Address) => TxRequest;
+        withdrawPending: () => TxRequest;
+    };
+    /** posts a bid with its deposit; returns the bid id */
+    post: (p: DipPost, s?: SendOptions) => Promise<Sent & {
+        id: bigint;
+    }>;
+    fund: (id: bigint, wei: bigint, s?: SendOptions) => Promise<Sent>;
+    withdraw: (id: bigint, wei: bigint, s?: SendOptions) => Promise<Sent>;
+    close: (id: bigint, s?: SendOptions) => Promise<Sent>;
+    /** pays exactly the quoted premium; returns the floor id */
+    buyFloor: (bidId: bigint, coins: bigint, s?: SendOptions) => Promise<Sent & {
+        id: bigint;
+        premium: bigint;
+    }>;
+    /** approves the coin to the desk if needed, then hands `coins` in for at least the dry run's payout less slippageBps */
+    exercise: (o: {
+        floorId: bigint;
+        coins: bigint;
+        token: Address;
+        slippageBps?: number;
+    }, s?: SendOptions) => Promise<Sent & {
+        paid: bigint;
+    }>;
+    end: (floorId: bigint, s?: SendOptions) => Promise<Sent>;
+    give: (floorId: bigint, to: Address, s?: SendOptions) => Promise<Sent>;
+    withdrawPending: (s?: SendOptions) => Promise<Sent>;
+};
+export type DipsModule = ReturnType<typeof dipsModule>;

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;