@pickhooks/sdk 0.0.0-stage → 0.2.0

package/dist/any.d.ts

@@ -0,0 +1,447 @@
+import { type Address, type Hex, type TransactionReceipt } from "viem";
+import { type PoolKey, poolIdOf } from "./infinity.js";
+import { type Ctx, type SendOptions, type Sent, type TxRequest } from "./tx.js";
+/**
+ * Hook any coin: a PancakeSwap Infinity pool BNB / coin next to a coin's own pools, with a normal dynamic LP fee (routers
+ * see a plain pool). Two lines:
+ *  - main (v3, factory 0x1662…be117): after a swap the hook closes the gap to the coin's PancakeSwap V2 pair in the same
+ *    transaction (arb recapture) and gives the trader a share of that profit. Fees and recapture profits are split:
+ *    opener side (and its jackpot), then of the platform's part a share for the pool's partner and for a listed router.
+ *  - tax (flap tax coins, off until addresses.anyTaxFactory is set): in flap's anti-farmer state the coin's tax applies in
+ *    the pool like on its main pool; sells must pay their coins in first (the SDK does that), terminals sell in the main
+ *    pool. No recapture, partners or routers on this line.
+ */
+export type { PoolKey } from "./infinity.js";
+export { poolIdOf } from "./infinity.js";
+export type AnyLine = "main" | "tax";
+/** A pool id, a pool key, or a pool read with pools()/pool(). */
+export type PoolRef = Hex | PoolKey | {
+    id: Hex;
+    key: PoolKey;
+    line?: AnyLine;
+};
+/** What a pool does, fixed when it opened (basis points unless named otherwise). */
+export type PoolConfig = {
+    /** the LP fee, 20 to 100 (0.2 % to 1 %) */
+    feeBps: number;
+    /** the LP fee for wallets holding at least holderMin $hooks (raw, 18 decimals); holderMin 0 means none */
+    holderFeeBps: number;
+    holderMin: bigint;
+    /** the opener's side of every BNB fee and recapture profit (the jackpot's share comes out of it) */
+    openerBps: number;
+    potBps: number;
+    /** the fire: share of every buy's coins burned out of the coin's chest */
+    chestBps: number;
+    jackpotShareBps: number;
+    jackpotSilence: number;
+    jackpotMinBuy: bigint;
+    bonusBps: number;
+    bonusLock: number;
+    bonusMinBuy: bigint;
+    bonusCap: bigint;
+    /** main line: the coin's V2 pair the hook recaptures against; zero address: no recapture (always on the tax line) */
+    pair: Address;
+    /** main line: the trader's share of each recapture */
+    traderBps: number;
+    /** main line: the partner that brought the pool, and its share of the platform's part; zero address: none */
+    partner: Address;
+    partnerBps: number;
+    /** tax line: the coin had the Infinity vault on its tax list when the pool opened */
+    vaultTaxed: boolean;
+};
+export type PoolPosition = {
+    index: number;
+    tickLower: number;
+    tickUpper: number;
+    liquidity: bigint;
+    unlockAt: number;
+};
+/** a flap tax coin's tax as it stands now (it changes over time), and what of it applies in a tax-line pool */
+export type TaxLive = {
+    /** flap's state: 2 anti-farmer (every pool transfer taxed, the vault too), 3 only the main pool taxed, 4 tax free */
+    state: number;
+    buyBps: number;
+    sellBps: number;
+    /** when the anti-farmer time ends (unix); the state moves on at the first sell into the main pool after it */
+    antiFarmerEnd: number;
+    /** the coin has the Infinity vault on its tax list */
+    vaultTaxed: boolean;
+    /** the tax a buy and a sell pay in the pool right now */
+    poolBuyBps: number;
+    poolSellBps: number;
+    /** sells must pay their coins in first (the SDK's sell does; a plain router sell is refused with PayFirst) */
+    payFirst: boolean;
+    /** the coin's quote token (WBNB, or a stock token such as QQQB) */
+    quote: Address;
+};
+export type AnyPool = {
+    id: Hex;
+    line: AnyLine;
+    /** the factory that opened the pool and its hook: every call for this pool goes there */
+    factory: Address;
+    hook: Address;
+    key: PoolKey;
+    token: Address;
+    name: string;
+    symbol: string;
+    decimals: number;
+    /** slot n is the pool with tick spacing 10 + n; a coin can have up to 50 pools per line */
+    slot: number;
+    opener: Address;
+    start: number;
+    config: PoolConfig;
+    buys: number;
+    sells: number;
+    volumeBnb: bigint;
+    feesBnb: bigint;
+    burned: bigint;
+    burnedFromChest: bigint;
+    /** the jackpot, BNB */
+    pot: bigint;
+    lastBuyer: Address;
+    lastBuyTime: number;
+    bonusPot: bigint;
+    bonusGiven: bigint;
+    /** main line: BNB profit of all recaptures, and how many */
+    recaptured: bigint;
+    recaptures: number;
+    /** main line: router credits for buys here that the next collect funds */
+    routerDue: bigint;
+    /** coins in the coin's chest (the fire), shared by all its pools of the line */
+    chest: bigint;
+    /** tax line: the coin's tax now; null on the main line */
+    tax: TaxLive | null;
+    positions: PoolPosition[];
+    sqrtPriceX96: bigint;
+    tick: number;
+    /** the LP fee as the pool manager stores it, hundredths of a bip */
+    lpFee: number;
+    /** coins per BNB in whole units, at the pool's price */
+    price: number;
+    /** the latest block's timestamp when this was read */
+    chainNow: number;
+};
+export type CoinCheck = {
+    token: Address;
+    /** which line takes the coin: the main one, or the tax line for a flap tax coin (when it is on) */
+    line: AnyLine;
+    factory: Address;
+    /** factory.check(): 0 the coin can get a pool, else the reason (see text) */
+    code: number;
+    ok: boolean;
+    text: string;
+    name: string;
+    symbol: string;
+    decimals: number;
+    /** the price a pool opens at (coin per BNB, Q64.96) and where it comes from */
+    sqrtPrice: bigint;
+    priceSource: Address;
+    /** BNB (tax line: BNB of value) in that price source: a new pool must be at least this deep for buys */
+    depth: bigint;
+    /** coins per BNB in whole units */
+    price: number;
+    /** the coin's owner() if it has one (it could pause or blacklist); null for flap tax coins */
+    owner: Address | null;
+    slotsUsed: number[];
+    /** the first free slot, or null when all 50 are taken */
+    freeSlot: number | null;
+    /** the coin's V2 pair against WBNB (zero address when none): what a main-line pool recaptures against */
+    pair: Address;
+    /** tax line: the coin's tax now */
+    tax: TaxLive | null;
+};
+export type RangeKind = "ladder" | "ladder10" | "around";
+export type OpenParams = {
+    token: Address;
+    slot: number;
+    feeBps: number;
+    holderFeeBps: number;
+    holderMin: bigint;
+    chestBps: number;
+    potShareBps: number;
+    jackpotShareBps: number;
+    jackpotSilence: number;
+    jackpotMinBuy: bigint;
+    bonusBps: number;
+    bonusLock: number;
+    bonusMinBuy: bigint;
+    bonusCap: bigint;
+    expectedSqrtPrice: bigint;
+    maxMoveBps: number;
+    tickLower: number;
+    tickUpper: number;
+    tokenAmount: bigint;
+    /** main line only */
+    partner: Address;
+    noRecapture: boolean;
+};
+/** A pool's rules in plain numbers; everything has the site's default. */
+export type OpenOptions = {
+    token: Address;
+    /** coins the opener puts in (raw units); a pool must be at least as deep as the coin's main pool, see depthNeeds() */
+    tokenAmount: bigint;
+    /** BNB for a range around the price; ladders take none */
+    bnb?: bigint;
+    /**
+     * ladder: coins only from the price up, no top; ladder10: coins only up to 10x (default); around: coins and BNB, half
+     * to twice the price; or exact ticks (fitLadder() gives the widest ladder the coins can make as deep as the main pool)
+     */
+    range?: RangeKind | {
+        tickLower: number;
+        tickUpper: number;
+    };
+    slot?: number;
+    /** default 30 (0.3 %) */
+    feeBps?: number;
+    /** default 5 (0.05 %) for wallets with holderMin $hooks; holderMin 0n switches it off */
+    holderFeeBps?: number;
+    /** default 10,000 $hooks */
+    holderMin?: bigint;
+    /** the fire, default 200 (2 % of every buy's coins burned out of the chest) */
+    chestBps?: number;
+    /** lock to earn: default 500 (5 %) for 7 days, buys from 0.05 BNB; false for none */
+    bonus?: false | {
+        bps?: number;
+        lockSeconds?: number;
+        minBuy?: bigint;
+        cap?: bigint;
+    };
+    /** default off; on: the opener's side feeds a pot the last buyer wins after `silenceSeconds` without a qualifying buy */
+    jackpot?: false | {
+        potShareBps?: number;
+        shareBps?: number;
+        silenceSeconds?: number;
+        minBuy?: bigint;
+    };
+    /** main line: a partner listed by pickhooks (partnerBps > 0) that brought the pool */
+    partner?: Address;
+    /** main line, default true: the hook closes the gap to the coin's V2 pair after every swap */
+    recapture?: boolean;
+    /** how far the price may move between the check and the open, default 100 (1 %) */
+    maxMoveBps?: number;
+};
+export type Recapture = {
+    profit: bigint;
+    toTrader: bigint;
+    soldHere: boolean;
+};
+export type TradeResult = Sent & {
+    side: "buy" | "sell";
+    /** what the quote said (after a tax-line coin's tax) and the minimum the trade accepted (on the pool's own amount) */
+    quoted: bigint;
+    minOut: bigint;
+    amountIn: bigint;
+    /** from the hook's Traded event: coins out of the pool for a buy (before a buy tax), BNB for a sell */
+    amountOut: bigint;
+    /** main line: the recapture in this transaction, if the hook closed a gap */
+    recapture: Recapture | null;
+    /** main line: BNB credited to a listed router's payout wallet by this trade */
+    routerCredit: bigint;
+};
+export type Earnings = {
+    /** BNB claim() pays on the main line: opener side, jackpot wins, recapture shares, a partner's share */
+    owed: bigint;
+    /** BNB credited to this wallet as a router payout, and how much of it claimRouter() pays now (funded by collects) */
+    routerCredit: bigint;
+    routerClaimable: bigint;
+    /** this address as a partner: its share of the platform's part in pools opened with it (0: not listed) */
+    partnerBps: number;
+    /** BNB claim({ line: "tax" }) pays on the tax line (0 while it is off) */
+    taxOwed: bigint;
+};
+export type AnyQuote = {
+    /** what the trader gets: coins after the buy tax, or BNB */
+    amountOut: bigint;
+    /** the pool's own amount (coins before the buy tax): what a router's minimum counts */
+    gross: bigint;
+    /** the tax this trade pays in the pool now (tax line), basis points */
+    taxBps: number;
+    gasEstimate: bigint;
+};
+export declare const MIN_TICK = -887272;
+export declare const MAX_TICK = 887272;
+/** AnyTaxHook.QUOTE = keccak256("pickhooks.any.tax.quote"): a sell quote carries it to look past the pay-first guard */
+export declare const TAX_QUOTE_MARK: Hex;
+/** The tick of a sqrt price (Q64.96), rounded down. */
+export declare function tickOf(sqrtPrice: bigint): number;
+/**
+ * The ticks of a range for a slot. The pool's price is coin per BNB, so the coin gets dearer as the tick falls.
+ * ladder: coins only, from the price up with no top; ladder10: coins only, up to 10x; around: half to twice the price.
+ */
+export declare function rangeFor(kind: RangeKind, sqrtPrice: bigint, slot: number): {
+    lower: number;
+    upper: number;
+};
+/**
+ * About how many coins (raw) and how much BNB a range needs so the new pool is as deep for buys as the coin's main pool
+ * (the factory refuses a shallower one with TooShallow), with a 3 % margin. Depth is liquidity / sqrt price, the number a
+ * V2 pool's BNB reserve means. A tax-line coin arrives less its sell tax: pass `sellTaxBps` (CoinCheck.tax.poolSellBps).
+ */
+export declare function depthNeeds(check: Pick<CoinCheck, "sqrtPrice" | "depth">, range: RangeKind, slot: number, sellTaxBps?: number): {
+    coins: bigint;
+    bnb: bigint;
+};
+/**
+ * The widest coins-only ladder right above the price that `coins` can make at least as deep as the coin's main pool
+ * (plus marginBps, default 500): the way to open with few coins (depth sits at the price, the ladder ends sooner).
+ * A tax-line coin arrives less its sell tax. Null when the coins cannot fill even one tick spacing.
+ */
+export declare function fitLadder(check: Pick<CoinCheck, "sqrtPrice" | "depth">, coins: bigint, slot: number, sellTaxBps?: number, marginBps?: number): {
+    tickLower: number;
+    tickUpper: number;
+} | null;
+/** The site's link that opens a pool with this partner named (the open form reads ?partner=). */
+export declare function partnerLink(partner: Address, site?: string): string;
+/** what arrives of `amount` after a tax of `bps` (flap floors the tax) */
+export declare const afterTax: (amount: bigint, bps: number) => bigint;
+export declare function anyModule(ctx: Ctx): {
+    /** the main factory and hook, and whether the tax line is on */
+    factory: `0x${string}`;
+    hook: `0x${string}`;
+    taxLineOn: boolean;
+    terms: () => Promise<{
+        owner: Address;
+        platformWallet: Address;
+        openerBps: number;
+        traderBps: number;
+        hook: Address;
+    }>;
+    check: (token: Address) => Promise<CoinCheck>;
+    taxOf: (token: Address) => Promise<TaxLive>;
+    depthNeeds: typeof depthNeeds;
+    fitLadder: typeof fitLadder;
+    rangeFor: typeof rangeFor;
+    count: (line?: AnyLine) => Promise<number>;
+    pools: (o?: {
+        limit?: number;
+        offset?: number;
+        line?: AnyLine;
+    }) => Promise<AnyPool[]>;
+    pool: (ref: PoolRef) => Promise<AnyPool | null>;
+    poolsOf: (token: Address) => Promise<AnyPool[]>;
+    key: (ref: PoolRef) => Promise<PoolKey>;
+    poolId: typeof poolIdOf;
+    earnings: (who: Address) => Promise<Earnings>;
+    router: (routerContract: Address) => Promise<{
+        payout: Address;
+        bps: number;
+    }>;
+    partnerBps: (partner: Address) => Promise<number>;
+    partnerLink: (partner: Address) => string;
+    bonusOf: (ref: PoolRef, who: Address) => Promise<{
+        bought: bigint;
+        locked: bigint;
+        owed: bigint;
+        total: bigint;
+        unlockAt: number;
+    }>;
+    pendingFees: (ref: PoolRef) => Promise<{
+        bnb: bigint;
+        coins: bigint;
+    }>;
+    quote: (q: {
+        pool: PoolRef;
+        side: "buy" | "sell";
+        amount: bigint;
+        from?: Address;
+    }) => Promise<AnyQuote>;
+    sellApprovals: (owner: Address, token: Address, amount: bigint) => Promise<TxRequest[]>;
+    approvalFor: (owner: Address, token: Address, spender: Address, amount: bigint) => Promise<TxRequest | null>;
+    openParams: (o: OpenOptions, checked?: CoinCheck) => Promise<{
+        params: OpenParams;
+        value: bigint;
+        check: CoinCheck;
+    }>;
+    readTrade: (receipt: TransactionReceipt) => {
+        side: "buy" | "sell" | null;
+        tokens: bigint;
+        bnb: bigint;
+        recapture: Recapture | null;
+        routerCredit: bigint;
+    };
+    build: {
+        buy: (b: {
+            key: PoolKey;
+            bnbIn: bigint;
+            minOut: bigint;
+            deadline?: bigint;
+            recapture?: boolean;
+        }) => TxRequest;
+        sell: (s: {
+            key: PoolKey;
+            amount: bigint;
+            minOut: bigint;
+            deadline?: bigint;
+            recapture?: boolean;
+        }) => TxRequest;
+        sellPayFirst: (s: {
+            key: PoolKey;
+            amount: bigint;
+            minOut: bigint;
+            deadline?: bigint;
+        }) => TxRequest;
+        open: (params: OpenParams, value?: bigint, line?: AnyLine) => TxRequest;
+        /** main line: opener side, jackpot wins, recapture shares, a partner's share; { line: "tax" } for the tax line's hook */
+        claim: (o?: {
+            line?: AnyLine;
+        }) => TxRequest;
+        /** a router's payout wallet takes what collects have funded of its credit */
+        claimRouter: () => TxRequest;
+        /** anyone: collects the pool's fees and books them (funds router credits) */
+        collect: (ref: PoolRef) => Promise<TxRequest>;
+        settleJackpot: (ref: PoolRef) => Promise<TxRequest>;
+        fundPot: (ref: PoolRef, wei: bigint) => Promise<TxRequest>;
+        /** these move coins into the hook: approve the coin to the hook first (approvalFor) */
+        feedChest: (token: Address, amount: bigint, line?: AnyLine) => Promise<TxRequest>;
+        fundBonus: (ref: PoolRef, amount: bigint) => Promise<TxRequest>;
+        lockBonus: (ref: PoolRef, amount: bigint) => Promise<TxRequest>;
+        unlockBonus: (ref: PoolRef) => Promise<TxRequest>;
+        /** the opener: more liquidity (approve the coin to the factory first), or a position out after its 30 days */
+        addLiquidity: (token: Address, slot: number, tickLower: number, tickUpper: number, tokenAmount: bigint, bnb?: bigint, line?: AnyLine) => TxRequest;
+        removeLiquidity: (ref: PoolRef, index: number) => Promise<TxRequest>;
+    };
+    buy: (b: {
+        pool: PoolRef;
+        bnbIn: bigint;
+        slippageBps?: number;
+        minOut?: bigint;
+        recapture?: boolean;
+        deadline?: bigint;
+    }, o?: SendOptions) => Promise<TradeResult>;
+    sell: (s: {
+        pool: PoolRef;
+        amount: bigint;
+        slippageBps?: number;
+        minOut?: bigint;
+        recapture?: boolean;
+        deadline?: bigint;
+    }, o?: SendOptions) => Promise<TradeResult>;
+    open: (o: OpenOptions, s?: SendOptions) => Promise<Sent & {
+        id: Hex;
+        params: OpenParams;
+        line: AnyLine;
+    }>;
+    claim: (s?: SendOptions & {
+        line?: AnyLine;
+    }) => Promise<Sent>;
+    claimRouter: (s?: SendOptions) => Promise<Sent>;
+    collect: (ref: PoolRef, s?: SendOptions) => Promise<Sent>;
+    settleJackpot: (ref: PoolRef, s?: SendOptions) => Promise<Sent>;
+    fundPot: (ref: PoolRef, wei: bigint, s?: SendOptions) => Promise<Sent>;
+    feedChest: (token: Address, amount: bigint, s?: SendOptions & {
+        line?: AnyLine;
+    }) => Promise<Sent>;
+    fundBonus: (ref: PoolRef, amount: bigint, s?: SendOptions) => Promise<Sent>;
+    lockBonus: (ref: PoolRef, amount: bigint, s?: SendOptions) => Promise<Sent>;
+    unlockBonus: (ref: PoolRef, s?: SendOptions) => Promise<Sent>;
+    addLiquidity: (ref: PoolRef, range: {
+        tickLower: number;
+        tickUpper: number;
+    }, tokenAmount: bigint, bnb?: bigint, s?: SendOptions) => Promise<Sent>;
+    removeLiquidity: (ref: PoolRef, index: number, s?: SendOptions) => Promise<Sent>;
+    /** the tax line's hook: anyone sends a surplus to its place (the coin's own into the fire, other tokens to the platform) */
+    sweep: (token: Address, s?: SendOptions) => Promise<Sent>;
+    lineOf: (ref: PoolRef) => Promise<AnyLine>;
+    lineOfFactory: (f: Address) => AnyLine;
+};
+export type AnyModule = ReturnType<typeof anyModule>;