@pickhooks/sdk 0.0.0-stage → 0.4.0

package/dist/tx.d.ts

@@ -0,0 +1,72 @@
+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;
+/** A deadline from the later of this machine's clock and the chain's (a skewed clock or a fork ahead of real time). */
+export declare function chainDeadline(ctx: Ctx, seconds?: number): Promise<bigint>;
+/** amount less a slippage in basis points */
+export declare const minusBps: (amount: bigint, bps: number) => bigint;

package/dist/tx.js

@@ -0,0 +1,78 @@
+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);
+/** A deadline from the later of this machine's clock and the chain's (a skewed clock or a fork ahead of real time). */
+export async function chainDeadline(ctx, seconds = 600) {
+    const local = Math.floor(Date.now() / 1000);
+    const chain = await ctx.pub
+        .getBlock()
+        .then((b) => Number(b.timestamp))
+        .catch(() => local);
+    return BigInt(Math.max(local, chain) + 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;

package/dist/v2.d.ts

@@ -0,0 +1,106 @@
+import { type Address } from "viem";
+import type { Addresses } from "./addresses.js";
+import { type Ctx, type TxRequest } from "./tx.js";
+/**
+ * PancakeSwap V2: every sticky coin (and every rules coin since 03.10.) has a V2 pair next to its V3 pool, at the same
+ * start price. A dark launch puts the whole round's BNB into that pair, so right after the birth the pair is the venue
+ * with the BNB and the V3 curve holds only coins above the price: a sell into V3 would get almost nothing ("SPL").
+ * Terminals route to the better pool by themselves; the SDK quotes both and picks the better one (sticky.quote).
+ */
+export declare const v2RouterAbi: readonly [{
+    readonly name: "getAmountsOut";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "uint256";
+        readonly name: "amountIn";
+    }, {
+        readonly type: "address[]";
+        readonly name: "path";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256[]";
+        readonly name: "amounts";
+    }];
+}, {
+    readonly name: "swapExactETHForTokensSupportingFeeOnTransferTokens";
+    readonly type: "function";
+    readonly stateMutability: "payable";
+    readonly inputs: readonly [{
+        readonly type: "uint256";
+        readonly name: "amountOutMin";
+    }, {
+        readonly type: "address[]";
+        readonly name: "path";
+    }, {
+        readonly type: "address";
+        readonly name: "to";
+    }, {
+        readonly type: "uint256";
+        readonly name: "deadline";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly name: "swapExactTokensForETHSupportingFeeOnTransferTokens";
+    readonly type: "function";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly type: "uint256";
+        readonly name: "amountIn";
+    }, {
+        readonly type: "uint256";
+        readonly name: "amountOutMin";
+    }, {
+        readonly type: "address[]";
+        readonly name: "path";
+    }, {
+        readonly type: "address";
+        readonly name: "to";
+    }, {
+        readonly type: "uint256";
+        readonly name: "deadline";
+    }];
+    readonly outputs: readonly [];
+}];
+export type Venue = "v3" | "v2";
+/** What a trade gets in the V2 pair, from the router (reverts when the coin has no pair or the pair is empty). */
+export declare function v2Quote(ctx: Ctx, q: {
+    token: Address;
+    side: "buy" | "sell";
+    amount: bigint;
+}): Promise<bigint>;
+/** A buy through the V2 router, BNB in. */
+export declare function buildV2Buy(a: Addresses, b: {
+    token: Address;
+    bnbIn: bigint;
+    minOut: bigint;
+    recipient: Address;
+    deadline?: bigint;
+    gasPct?: number;
+}): TxRequest;
+/** A sell through the V2 router for native BNB. Needs the coin approved to the V2 router. */
+export declare function buildV2Sell(a: Addresses, s: {
+    token: Address;
+    amount: bigint;
+    minOut: bigint;
+    recipient: Address;
+    deadline?: bigint;
+    gasPct?: number;
+}): TxRequest;
+/**
+ * The better of the two venues for this trade: the V3 pool (quoter) and the V2 pair (router). A venue that cannot
+ * quote (no pair, no BNB below the price, a refusing rule) counts as nothing; `errors` keeps what each one said.
+ */
+export declare function bestVenue(ctx: Ctx, quotes: {
+    v3: () => Promise<bigint>;
+    v2: () => Promise<bigint>;
+}): Promise<{
+    venue: Venue;
+    amountOut: bigint;
+    v3: bigint | null;
+    v2: bigint | null;
+    errors: {
+        v3?: unknown;
+        v2?: unknown;
+    };
+}>;

package/dist/v2.js

@@ -0,0 +1,61 @@
+import { encodeFunctionData, parseAbi } from "viem";
+import { deadlineIn } from "./tx.js";
+/**
+ * PancakeSwap V2: every sticky coin (and every rules coin since 03.10.) has a V2 pair next to its V3 pool, at the same
+ * start price. A dark launch puts the whole round's BNB into that pair, so right after the birth the pair is the venue
+ * with the BNB and the V3 curve holds only coins above the price: a sell into V3 would get almost nothing ("SPL").
+ * Terminals route to the better pool by themselves; the SDK quotes both and picks the better one (sticky.quote).
+ */
+export const v2RouterAbi = parseAbi([
+    "function getAmountsOut(uint256 amountIn, address[] path) view returns (uint256[] amounts)",
+    "function swapExactETHForTokensSupportingFeeOnTransferTokens(uint256 amountOutMin, address[] path, address to, uint256 deadline) payable",
+    "function swapExactTokensForETHSupportingFeeOnTransferTokens(uint256 amountIn, uint256 amountOutMin, address[] path, address to, uint256 deadline)",
+]);
+/** What a trade gets in the V2 pair, from the router (reverts when the coin has no pair or the pair is empty). */
+export async function v2Quote(ctx, q) {
+    const path = q.side === "buy" ? [ctx.a.wbnb, q.token] : [q.token, ctx.a.wbnb];
+    const amounts = (await ctx.pub.readContract({ address: ctx.a.v2Router, abi: v2RouterAbi, functionName: "getAmountsOut", args: [q.amount, path] }));
+    return amounts[amounts.length - 1];
+}
+/** A buy through the V2 router, BNB in. */
+export function buildV2Buy(a, b) {
+    return {
+        to: a.v2Router,
+        value: b.bnbIn,
+        data: encodeFunctionData({ abi: v2RouterAbi, functionName: "swapExactETHForTokensSupportingFeeOnTransferTokens", args: [b.minOut, [a.wbnb, b.token], b.recipient, b.deadline ?? deadlineIn()] }),
+        gasPct: b.gasPct,
+        label: "The buy",
+    };
+}
+/** A sell through the V2 router for native BNB. Needs the coin approved to the V2 router. */
+export function buildV2Sell(a, s) {
+    return {
+        to: a.v2Router,
+        value: 0n,
+        data: encodeFunctionData({ abi: v2RouterAbi, functionName: "swapExactTokensForETHSupportingFeeOnTransferTokens", args: [s.amount, s.minOut, [s.token, a.wbnb], s.recipient, s.deadline ?? deadlineIn()] }),
+        gasPct: s.gasPct,
+        label: "The sell",
+    };
+}
+/**
+ * The better of the two venues for this trade: the V3 pool (quoter) and the V2 pair (router). A venue that cannot
+ * quote (no pair, no BNB below the price, a refusing rule) counts as nothing; `errors` keeps what each one said.
+ */
+export async function bestVenue(ctx, quotes) {
+    const errors = {};
+    const [v3, v2] = await Promise.all([
+        quotes.v3().catch((e) => {
+            errors.v3 = e;
+            return null;
+        }),
+        quotes.v2().catch((e) => {
+            errors.v2 = e;
+            return null;
+        }),
+    ]);
+    void ctx;
+    if (v3 === null && v2 === null)
+        return { venue: "v3", amountOut: 0n, v3, v2, errors };
+    const venue = (v2 ?? 0n) > (v3 ?? 0n) ? "v2" : "v3";
+    return { venue, amountOut: venue === "v2" ? v2 : v3, v3, v2, errors };
+}

package/dist/v3.d.ts

@@ -0,0 +1,42 @@
+import { type Address, type TransactionReceipt } from "viem";
+import { type Addresses } from "./addresses.js";
+import { type Ctx, type TxRequest } from "./tx.js";
+/** A buy through the V3 SwapRouter, BNB in (the router wraps it). */
+export declare function buildV3Buy(a: Addresses, b: {
+    token: Address;
+    bnbIn: bigint;
+    minOut: bigint;
+    recipient: Address;
+    deadline?: bigint;
+    fee?: number;
+    gasPct?: number;
+}): TxRequest;
+/** A sell through the V3 SwapRouter for native BNB: swap to the router, unwrap to the seller. Needs the coin approved to the router. */
+export declare function buildV3Sell(a: Addresses, s: {
+    token: Address;
+    amount: bigint;
+    minOut: bigint;
+    recipient: Address;
+    deadline?: bigint;
+    fee?: number;
+    gasPct?: number;
+}): TxRequest;
+/** What a trade gets in the V3 pool, from the QuoterV2 (it runs the swap, so a coin's refusing rule fails it: raw error). */
+export declare function v3Quote(ctx: Ctx, q: {
+    token: Address;
+    side: "buy" | "sell";
+    amount: bigint;
+    fee?: number;
+}): Promise<bigint>;
+/** The approval of `spender` (default the V3 router) a sell needs, or null when it is in place. */
+export declare function approvalFor(ctx: Ctx, owner: Address, token: Address, amount: bigint, spender?: Address, label?: string): Promise<TxRequest | null>;
+/** Coins of `token` that reached `to` in a receipt (its Transfer events). */
+export declare function receivedOf(receipt: TransactionReceipt, token: Address, to: Address): bigint;
+/**
+ * Coins a buy of `bnbIn` would get from a V3 pool, estimated as a constant product on the pool's active liquidity at its
+ * current price, the fee taken off the input. PancakeSwap's QuoterV2 cannot run a buy a coin's rule refuses, and it does
+ * not pass the coin's error on ("Unexpected error"), so this estimate is what names the rule then. Never use it as a minOut.
+ */
+export declare function v3EstimateBuy(ctx: Ctx, pool: Address, token: Address, bnbIn: bigint, fee?: number): Promise<bigint>;
+/** BNB per coin at a V3 pool's sqrt price (V3 prices token1 per token0). */
+export declare function v3PriceBnb(sqrtPriceX96: bigint, token: Address, wbnb: Address): number;

package/dist/v3.js

@@ -0,0 +1,98 @@
+import { encodeFunctionData, isAddressEqual, maxUint256, parseAbi, parseEventLogs } from "viem";
+import { erc20Abi, v3QuoterAbi, v3RouterAbi } from "./abis/common.js";
+import { LIMITS } from "./addresses.js";
+import { deadlineIn } from "./tx.js";
+/**
+ * PancakeSwap V3, shared by the products whose coins trade in a V3 pool of 1 % (coins with rules in the coin, v1 and v2,
+ * and sticky coins): the SwapRouter's buy and sell, the QuoterV2, the sell approval, and what a receipt delivered.
+ */
+const transferAbi = [
+    {
+        type: "event",
+        name: "Transfer",
+        inputs: [
+            { name: "from", type: "address", indexed: true },
+            { name: "to", type: "address", indexed: true },
+            { name: "value", type: "uint256", indexed: false },
+        ],
+        anonymous: false,
+    },
+];
+/** A buy through the V3 SwapRouter, BNB in (the router wraps it). */
+export function buildV3Buy(a, b) {
+    return {
+        to: a.v3Router,
+        value: b.bnbIn,
+        data: encodeFunctionData({
+            abi: v3RouterAbi,
+            functionName: "exactInputSingle",
+            args: [{ tokenIn: a.wbnb, tokenOut: b.token, fee: b.fee ?? LIMITS.stickyPoolFee, recipient: b.recipient, deadline: b.deadline ?? deadlineIn(), amountIn: b.bnbIn, amountOutMinimum: b.minOut, sqrtPriceLimitX96: 0n }],
+        }),
+        gasPct: b.gasPct,
+        label: "The buy",
+    };
+}
+/** A sell through the V3 SwapRouter for native BNB: swap to the router, unwrap to the seller. Needs the coin approved to the router. */
+export function buildV3Sell(a, s) {
+    const swap = encodeFunctionData({
+        abi: v3RouterAbi,
+        functionName: "exactInputSingle",
+        args: [{ tokenIn: s.token, tokenOut: a.wbnb, fee: s.fee ?? LIMITS.stickyPoolFee, recipient: a.v3Router, deadline: s.deadline ?? deadlineIn(), amountIn: s.amount, amountOutMinimum: s.minOut, sqrtPriceLimitX96: 0n }],
+    });
+    const unwrap = encodeFunctionData({ abi: v3RouterAbi, functionName: "unwrapWETH9", args: [s.minOut, s.recipient] });
+    return { to: a.v3Router, value: 0n, data: encodeFunctionData({ abi: v3RouterAbi, functionName: "multicall", args: [[swap, unwrap]] }), gasPct: s.gasPct, label: "The sell" };
+}
+/** What a trade gets in the V3 pool, from the QuoterV2 (it runs the swap, so a coin's refusing rule fails it: raw error). */
+export async function v3Quote(ctx, q) {
+    const buy = q.side === "buy";
+    const r = await ctx.pub.simulateContract({
+        address: ctx.a.v3Quoter,
+        abi: v3QuoterAbi,
+        functionName: "quoteExactInputSingle",
+        args: [{ tokenIn: buy ? ctx.a.wbnb : q.token, tokenOut: buy ? q.token : ctx.a.wbnb, amountIn: q.amount, fee: q.fee ?? LIMITS.stickyPoolFee, sqrtPriceLimitX96: 0n }],
+    });
+    return r.result[0];
+}
+/** The approval of `spender` (default the V3 router) a sell needs, or null when it is in place. */
+export async function approvalFor(ctx, owner, token, amount, spender = ctx.a.v3Router, label = "The approval") {
+    const have = await ctx.pub.readContract({ address: token, abi: erc20Abi, functionName: "allowance", args: [owner, spender] });
+    if (have >= amount)
+        return null;
+    return { to: token, value: 0n, data: encodeFunctionData({ abi: erc20Abi, functionName: "approve", args: [spender, maxUint256] }), label };
+}
+/** Coins of `token` that reached `to` in a receipt (its Transfer events). */
+export function receivedOf(receipt, token, to) {
+    const logs = parseEventLogs({ abi: transferAbi, logs: receipt.logs.filter((l) => isAddressEqual(l.address, token)), eventName: "Transfer" });
+    return logs.filter((l) => isAddressEqual(l.args.to, to)).reduce((x, l) => x + l.args.value, 0n);
+}
+const poolStateAbi = parseAbi([
+    "function slot0() view returns (uint160 sqrtPriceX96, int24 tick, uint16, uint16, uint16, uint32, bool)",
+    "function liquidity() view returns (uint128)",
+]);
+/**
+ * Coins a buy of `bnbIn` would get from a V3 pool, estimated as a constant product on the pool's active liquidity at its
+ * current price, the fee taken off the input. PancakeSwap's QuoterV2 cannot run a buy a coin's rule refuses, and it does
+ * not pass the coin's error on ("Unexpected error"), so this estimate is what names the rule then. Never use it as a minOut.
+ */
+export async function v3EstimateBuy(ctx, pool, token, bnbIn, fee = LIMITS.stickyPoolFee) {
+    const [slot0, liquidity] = await Promise.all([
+        ctx.pub.readContract({ address: pool, abi: poolStateAbi, functionName: "slot0" }),
+        ctx.pub.readContract({ address: pool, abi: poolStateAbi, functionName: "liquidity" }),
+    ]);
+    const sqrtP = slot0[0];
+    if (sqrtP === 0n || liquidity === 0n)
+        return 0n;
+    const Q96 = 1n << 96n;
+    const r0 = (liquidity * Q96) / sqrtP;
+    const r1 = (liquidity * sqrtP) / Q96;
+    const [coins, bnb] = token.toLowerCase() < ctx.a.wbnb.toLowerCase() ? [r0, r1] : [r1, r0];
+    const dIn = (bnbIn * BigInt(1_000_000 - fee)) / 1000000n;
+    return (coins * dIn) / (bnb + dIn);
+}
+/** BNB per coin at a V3 pool's sqrt price (V3 prices token1 per token0). */
+export function v3PriceBnb(sqrtPriceX96, token, wbnb) {
+    const p = (Number(sqrtPriceX96) / 2 ** 96) ** 2;
+    if (p === 0)
+        return 0;
+    return token.toLowerCase() < wbnb.toLowerCase() ? p : 1 / p;
+}

package/dist/wallet.d.ts

@@ -0,0 +1,80 @@
+import { type Address } from "viem";
+import type { AgentLock, AgentsModule } from "./agents.js";
+import type { AnyModule, Earnings } from "./any.js";
+import type { CoinsModule } from "./coins.js";
+import type { DipFloor, DipsModule } from "./dips.js";
+import type { Lever2Module } from "./lever.js";
+import type { CallsModule, PoolsModule } from "./pools.js";
+import type { StickyModule } from "./sticky.js";
+import type { Ctx } from "./tx.js";
+import type { WatchMode } from "./watch.js";
+/**
+ * One address in: everything it holds on pickhooks, what it can sell right now, and what it can claim.
+ *
+ *   const w = await ph.wallet(address);
+ *   w.coins            // every pickhooks coin it holds, with mode, price, value and what is sellable now
+ *   w.claims           // BNB owed by the hooks (hook any coin, pools, curve calls, agents)
+ *   w.locks            // coins locked at the agents desk (vetoes, firing)
+ *   w.floors           // dip bid floors it holds
+ */
+export type WalletCoin = {
+    token: Address;
+    mode: WatchMode;
+    name: string;
+    symbol: string;
+    balance: bigint;
+    /** what a sell of the whole balance would be allowed right now: the balance, less (sticky: unlocked lots), or 0 with the reason */
+    sellable: bigint;
+    /** why not everything is sellable (a rule's sentence), or null */
+    refused: string | null;
+    priceBnb: number;
+    /** balance x price, in BNB */
+    valueBnb: number;
+    page: string;
+};
+export type WalletView = {
+    address: Address;
+    bnb: bigint;
+    coins: WalletCoin[];
+    /** the coins' value together, BNB */
+    valueBnb: number;
+    claims: {
+        /** hook any coin: recapture shares, opener and partner shares, router credits */
+        any: Earnings | null;
+        /** pools and curve calls: jackpot wins, rewards, a creator's share */
+        pools: bigint;
+        calls: bigint;
+        /** agents: jackpot wins, rewards, a creator's share */
+        agents: bigint;
+        /** all of the above in BNB (router credits counted as claimable) */
+        totalBnb: bigint;
+    };
+    /** coins locked at the agents desk, per agent coin */
+    locks: ({
+        token: Address;
+        symbol: string;
+    } & AgentLock)[];
+    floors: DipFloor[];
+    /** factories the scan covered and how many coins each has (the newest `limit` per factory are scanned) */
+    scanned: {
+        mode: WatchMode;
+        count: number;
+        scanned: number;
+    }[];
+};
+type Mods = {
+    sticky: StickyModule;
+    sticky2: StickyModule;
+    coins: CoinsModule;
+    pools: PoolsModule;
+    calls: CallsModule;
+    lever: Lever2Module;
+    agents: AgentsModule;
+    any: AnyModule;
+    dips: DipsModule;
+};
+export declare function walletModule(ctx: Ctx, mods: Mods): (who: Address, o?: {
+    limit?: number;
+}) => Promise<WalletView>;
+export type WalletModule = ReturnType<typeof walletModule>;
+export {};

package/dist/wallet.js

@@ -0,0 +1,115 @@
+import { formatEther, isAddressEqual } from "viem";
+import { agentsFactoryAbi } from "./abis/agents.js";
+import { callsFactoryAbi } from "./abis/calls.js";
+import { erc20Abi } from "./abis/common.js";
+import { lever2FactoryAbi } from "./abis/lever2.js";
+import { poolsFactoryAbi } from "./abis/pools.js";
+import { stickyFactoryAbi } from "./abis/sticky.js";
+import { sticky2FactoryAbi } from "./abis/sticky2.js";
+import { v1FactoryAbi } from "./abis/v1.js";
+import { v2FactoryAbi } from "./abis/v2.js";
+import { ZERO_ADDRESS } from "./addresses.js";
+export function walletModule(ctx, mods) {
+    const { pub, a } = ctx;
+    const page = (mode, token) => {
+        const path = { sticky: "s", sticky2: "s", rules: "c", "rules-v1": "c", pools: "h", calls: "z", lever: "l", agents: "a", any: "any" }[mode];
+        return `${ctx.site}/${path}/${token}`;
+    };
+    const factories = [
+        { mode: "sticky", address: a.stickyFactory, abi: stickyFactoryAbi },
+        { mode: "sticky2", address: a.sticky2Factory, abi: sticky2FactoryAbi },
+        { mode: "rules", address: a.coinsV2Factory, abi: v2FactoryAbi },
+        { mode: "rules-v1", address: a.coinsV1Factory, abi: v1FactoryAbi },
+        { mode: "pools", address: a.poolsFactory, abi: poolsFactoryAbi },
+        { mode: "calls", address: a.callsFactory, abi: callsFactoryAbi },
+        { mode: "lever", address: a.lever2Factory, abi: lever2FactoryAbi },
+        { mode: "agents", address: a.agentsFactory, abi: agentsFactoryAbi },
+    ];
+    /** The newest `limit` coins of every factory. */
+    async function tokens(limit) {
+        const live = factories.filter((f) => !isAddressEqual(f.address, ZERO_ADDRESS));
+        const counts = await pub.multicall({ contracts: live.map((f) => ({ address: f.address, abi: f.abi, functionName: "coinCount" })), allowFailure: true });
+        const calls = [];
+        const owners = [];
+        const scanned = [];
+        live.forEach((f, i) => {
+            const n = counts[i].status === "success" ? Number(counts[i].result) : 0;
+            const from = Math.max(0, n - limit);
+            scanned.push({ mode: f.mode, count: n, scanned: n - from });
+            for (let j = n - 1; j >= from; j--) {
+                calls.push({ address: f.address, abi: f.abi, functionName: "coins", args: [BigInt(j)] });
+                owners.push(f.mode);
+            }
+        });
+        if (!calls.length)
+            return { list: [], scanned };
+        const res = await pub.multicall({ contracts: calls, allowFailure: true });
+        const list = [];
+        res.forEach((r, i) => {
+            if (r.status === "success")
+                list.push({ mode: owners[i], token: r.result });
+        });
+        return { list, scanned };
+    }
+    /** A held coin's name, symbol, price and what is sellable now, by mode. */
+    async function detail(mode, token, who, balance) {
+        const refusedOf = (r) => (r.ok ? null : (r.text ?? "The coin refused a sell right now."));
+        if (mode === "sticky" || mode === "sticky2") {
+            const m = mode === "sticky" ? mods.sticky : mods.sticky2;
+            const [c, w] = await Promise.all([m.coin(token), m.wallet(token, who)]);
+            return { name: c?.name ?? "", symbol: c?.symbol ?? "", sellable: w.sellable, refused: w.sellable < balance ? "Part of these coins is still locked by a rule; it unlocks over time." : null, priceBnb: c?.priceBnb ?? 0, valueBnb: (c?.priceBnb ?? 0) * Number(formatEther(balance)) };
+        }
+        if (mode === "rules" || mode === "rules-v1") {
+            const [c, r] = await Promise.all([mods.coins.coin(token), mods.coins.check({ token, side: "sell", wallet: who, amount: balance }).catch(() => ({ ok: false, kind: 0, name: "", text: "The coin could not be asked." }))]);
+            return { name: c?.name ?? "", symbol: c?.symbol ?? "", sellable: r.ok ? balance : 0n, refused: refusedOf(r), priceBnb: c?.priceBnb ?? 0, valueBnb: (c?.priceBnb ?? 0) * Number(formatEther(balance)) };
+        }
+        if (mode === "pools" || mode === "calls" || mode === "agents") {
+            const m = mode === "pools" ? mods.pools : mode === "calls" ? mods.calls : mods.agents;
+            const [c, r] = await Promise.all([m.coin(token), m.check({ token, side: "sell", wallet: who, amount: balance }).catch(() => ({ ok: false, kind: 0, name: "", text: "The pool could not be asked." }))]);
+            return { name: c?.name ?? "", symbol: c?.symbol ?? "", sellable: r.ok ? balance : 0n, refused: refusedOf(r), priceBnb: c?.priceBnb ?? 0, valueBnb: (c?.priceBnb ?? 0) * Number(formatEther(balance)) };
+        }
+        if (mode === "lever") {
+            const c = await mods.lever.coin(token);
+            return { name: c?.name ?? "", symbol: c?.symbol ?? "", sellable: balance, refused: null, priceBnb: c?.priceBnb ?? 0, valueBnb: (c?.priceBnb ?? 0) * Number(formatEther(balance)) };
+        }
+        const r = await pub.multicall({ contracts: [{ address: token, abi: erc20Abi, functionName: "name" }, { address: token, abi: erc20Abi, functionName: "symbol" }], allowFailure: true });
+        return { name: r[0].status === "success" ? String(r[0].result) : "", symbol: r[1].status === "success" ? String(r[1].result) : "", sellable: balance, refused: null, priceBnb: 0, valueBnb: 0 };
+    }
+    /**
+     * Everything a wallet holds on pickhooks: the newest `limit` coins of every factory (default 300) are checked for a
+     * balance, the held ones read in full. Claims and locks come from the hooks and the agents desk, floors from dip bids.
+     */
+    async function wallet(who, o = {}) {
+        const { list, scanned } = await tokens(o.limit ?? 300);
+        const [bnb, balances] = await Promise.all([
+            pub.getBalance({ address: who }),
+            list.length ? pub.multicall({ contracts: list.map((t) => ({ address: t.token, abi: erc20Abi, functionName: "balanceOf", args: [who] })), allowFailure: true }) : [],
+        ]);
+        const held = list.filter((_, i) => balances[i]?.status === "success" && balances[i].result > 0n).map((t, j) => ({ ...t, balance: balances[list.indexOf(t)].result, j }));
+        const coins = await Promise.all(held.map(async (h) => ({ token: h.token, mode: h.mode, balance: h.balance, page: page(h.mode, h.token), ...(await detail(h.mode, h.token, who, h.balance)) })));
+        coins.sort((x, y) => y.valueBnb - x.valueBnb);
+        const agentTokens = list.filter((t) => t.mode === "agents").map((t) => t.token);
+        const [any, pools, calls, agents, lockRows, floors] = await Promise.all([
+            mods.any.earnings(who).catch(() => null),
+            mods.pools.owed(who).catch(() => 0n),
+            mods.calls.owed(who).catch(() => 0n),
+            mods.agents.on ? mods.agents.owed(who).catch(() => 0n) : Promise.resolve(0n),
+            Promise.all(agentTokens.map((t) => mods.agents.locks(t, who).then((l) => ({ token: t, ...l })).catch(() => null))),
+            mods.dips.floorsOf(who).catch(() => []),
+        ]);
+        const locks = lockRows.filter((l) => l !== null && l.amount > 0n);
+        const lockSymbols = locks.length ? await pub.multicall({ contracts: locks.map((l) => ({ address: l.token, abi: erc20Abi, functionName: "symbol" })), allowFailure: true }) : [];
+        const anyBnb = any ? any.owed + any.routerClaimable + any.taxOwed : 0n;
+        return {
+            address: who,
+            bnb,
+            coins,
+            valueBnb: coins.reduce((s, c) => s + c.valueBnb, 0),
+            claims: { any, pools, calls, agents, totalBnb: anyBnb + pools + calls + agents },
+            locks: locks.map((l, i) => ({ ...l, symbol: lockSymbols[i]?.status === "success" ? String(lockSymbols[i].result) : "" })),
+            floors,
+            scanned,
+        };
+    }
+    return wallet;
+}