@pickhooks/sdk 0.2.0 → 0.4.0

package/dist/tlock.js

@@ -0,0 +1,185 @@
+// Time-lock encryption to a drand quicknet round, the same as the site's web/src/lib/hide-tlock.mjs (find the dev) and
+// what the dark launch's sealed bids use. Its own entry (@pickhooks/sdk/tlock), so the main SDK does not load BLS12-381.
+//
+// Ciphertext (U, V, W) for a 32 byte message M and the round's identity Q = hashToG1(sha256(round)):
+//   sigma random 32 bytes, r = H3(sigma, M) mod q
+//   U = r * G2                      (G2 point, 256 bytes in EIP-2537 encoding on chain)
+//   V = sigma xor H2(e(Q, pk)^r)
+//   W = M xor H4(sigma)
+// Opening needs drand's signature on the round (sig = s * Q): sigma = V xor H2(e(sig, U)), M = W xor H4(sigma).
+// The contracts check U == H3(sigma, M) * G2 and W == M xor H4(sigma) with the BLS12-381 precompile (HideMath.sol).
+import { bls12_381 as bls } from "@noble/curves/bls12-381";
+import { sha256 } from "@noble/hashes/sha2";
+import { keccak_256 } from "@noble/hashes/sha3";
+export const QUICKNET = {
+    chainHash: "52db9ba70e0cc0f6eaf7803dd07447a1f5477735fd3f661792ba94600c84e971",
+    publicKey: "83cf0f2896adee7eb8b5f01fcad3912212c437e0073e911fb90022d3e760183c8c4b450b6a0a6c3ac6a5776a2d1064510d1fec758c921cc22b0e17e63aaf4bcb5ed66304de9cf809bd274ca73bab4af5a6e9c76a4bc09e76eae8991ef5ece45a",
+    genesis: 1692803367,
+    period: 3,
+    dst: "BLS_SIG_BLS12381G1_XMD:SHA-256_SSWU_RO_NUL_",
+    urls: ["https://api.drand.sh", "https://api2.drand.sh", "https://api3.drand.sh", "https://drand.cloudflare.com"],
+};
+const Q = bls.params.r;
+const TWO256 = 1n << 256n;
+const TAG3 = new TextEncoder().encode("pickhooks.hide.H3");
+const TAG4 = new TextEncoder().encode("pickhooks.hide.H4");
+const TAG2 = new TextEncoder().encode("pickhooks.hide.H2");
+const G2 = bls.G2.ProjectivePoint;
+const G1 = bls.G1.ProjectivePoint;
+const hex = (b) => Array.from(b, (x) => x.toString(16).padStart(2, "0")).join("");
+const unhex = (h) => {
+    const s = h.startsWith("0x") ? h.slice(2) : h;
+    if (s.length % 2)
+        throw new Error("odd hex");
+    const out = new Uint8Array(s.length / 2);
+    for (let i = 0; i < out.length; i++)
+        out[i] = parseInt(s.slice(i * 2, i * 2 + 2), 16);
+    return out;
+};
+const concat = (...parts) => {
+    const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+    let o = 0;
+    for (const p of parts) {
+        out.set(p, o);
+        o += p.length;
+    }
+    return out;
+};
+const xor32 = (a, b) => {
+    const out = new Uint8Array(32);
+    for (let i = 0; i < 32; i++)
+        out[i] = a[i] ^ b[i];
+    return out;
+};
+const toBig = (b) => BigInt("0x" + (hex(b) || "0"));
+const be = (n, len) => unhex(n.toString(16).padStart(len * 2, "0"));
+const bytes32 = (x) => {
+    const b = typeof x === "string" ? unhex(x) : x;
+    if (b.length !== 32)
+        throw new Error("need 32 bytes");
+    return b;
+};
+/** r = (keccak(TAG3 || 0x01 || sigma || M) * 2^256 + keccak(TAG3 || 0x02 || sigma || M)) mod q, never 0. */
+export function h3(sigma, m) {
+    const a = toBig(keccak_256(concat(TAG3, Uint8Array.of(1), sigma, m)));
+    const b = toBig(keccak_256(concat(TAG3, Uint8Array.of(2), sigma, m)));
+    const r = (a * TWO256 + b) % Q;
+    return r === 0n ? 1n : r;
+}
+/** keccak(TAG4 || sigma). */
+export function h4(sigma) {
+    return keccak_256(concat(TAG4, sigma));
+}
+function h2(gt) {
+    return keccak_256(concat(TAG2, bls.fields.Fp12.toBytes(gt)));
+}
+/** First second at which drand publishes the round. */
+export function roundTime(round, net = QUICKNET) {
+    return net.genesis + (Number(round) - 1) * net.period;
+}
+/** First round published at or after `unixSeconds`. */
+export function roundAt(unixSeconds, net = QUICKNET) {
+    const t = Math.max(0, Math.ceil(unixSeconds) - net.genesis);
+    return Math.ceil(t / net.period) + 1;
+}
+/** The round's identity point: hash_to_G1(sha256(round as 8 bytes big endian)), as drand quicknet signs it. */
+export function roundPoint(round, net = QUICKNET) {
+    return G1.fromAffine(bls.G1.hashToCurve(sha256(be(BigInt(round), 8)), { DST: net.dst }).toAffine());
+}
+/** True when `sigHex` is drand's signature on `round` under the network's key. */
+export function verifyRoundSig(round, sigHex, net = QUICKNET) {
+    const sig = G1.fromHex(sigHex.startsWith("0x") ? sigHex.slice(2) : sigHex);
+    const pk = G2.fromHex(net.publicKey);
+    const lhs = bls.pairing(sig, G2.BASE);
+    const rhs = bls.pairing(roundPoint(round, net), pk);
+    return bls.fields.Fp12.eql(lhs, rhs);
+}
+/** G2 point to the 256 byte EIP-2537 encoding: x.c0, x.c1, y.c0, y.c1, each 64 bytes (16 zero bytes + 48). */
+export function g2ToEip(point) {
+    const { x, y } = point.toAffine();
+    return `0x${[x.c0, x.c1, y.c0, y.c1].map((v) => v.toString(16).padStart(128, "0")).join("")}`;
+}
+export function g2FromEip(h) {
+    const b = unhex(h);
+    if (b.length !== 256)
+        throw new Error("U must be 256 bytes");
+    const f = (i) => toBig(b.slice(i * 64, i * 64 + 64));
+    const Fp2 = bls.fields.Fp2;
+    const p = G2.fromAffine({ x: Fp2.create({ c0: f(0), c1: f(1) }), y: Fp2.create({ c0: f(2), c1: f(3) }) });
+    p.assertValidity();
+    return p;
+}
+/** The 32 byte message of a dark launch bid: the bidder (20 bytes), the step (1 byte), 11 zero bytes. */
+export function darkMessage(bidder, step) {
+    const a = unhex(bidder);
+    if (a.length !== 20)
+        throw new Error("bidder must be 20 bytes");
+    if (!(Number.isInteger(step) && step >= 0 && step < 24))
+        throw new Error("step must be 0 to 23");
+    return `0x${hex(concat(a, Uint8Array.of(step), new Uint8Array(11)))}`;
+}
+export function parseDarkMessage(m) {
+    const b = bytes32(m);
+    return { bidder: `0x${hex(b.slice(0, 20))}`, step: b[20], clean: b.slice(21).every((x) => x === 0) };
+}
+/**
+ * Encrypts 32 bytes to a drand round. Returns hex ready for the contracts: u (256 bytes), v and w (32 each).
+ * `opts.sigma` and `opts.publicKey` exist for tests only.
+ */
+export function encrypt(round, message, opts = {}) {
+    const net = opts.net ?? QUICKNET;
+    const m = bytes32(message);
+    const sigma = opts.sigma ? bytes32(opts.sigma) : crypto.getRandomValues(new Uint8Array(32));
+    const r = h3(sigma, m);
+    const pk = G2.fromHex(opts.publicKey ?? net.publicKey);
+    const U = G2.BASE.multiply(r);
+    const gid = bls.pairing(roundPoint(round, net), pk.multiply(r));
+    const V = xor32(sigma, h2(gid));
+    const W = xor32(m, h4(sigma));
+    return { u: g2ToEip(U), v: `0x${hex(V)}`, w: `0x${hex(W)}`, round: Number(round), sigma: `0x${hex(sigma)}` };
+}
+/** Opens a ciphertext with drand's signature on its round: { sigma, message }, or null when it does not open. */
+export function decrypt(c, sigHex) {
+    let U;
+    try {
+        U = g2FromEip(c.u);
+    }
+    catch {
+        return null;
+    }
+    const sig = G1.fromHex(sigHex.startsWith("0x") ? sigHex.slice(2) : sigHex);
+    const gid = bls.pairing(sig, U);
+    const sigma = xor32(bytes32(c.v), h2(gid));
+    const m = xor32(bytes32(c.w), h4(sigma));
+    if (!opens(c, sigma, m))
+        return null;
+    return { sigma: `0x${hex(sigma)}`, message: `0x${hex(m)}` };
+}
+/** The contract's own check, in JS: U == H3(sigma, M) * G2 and W == M xor H4(sigma). */
+export function opens(c, sigma, message) {
+    const s = bytes32(sigma);
+    const m = bytes32(message);
+    if (hex(xor32(m, h4(s))) !== hex(bytes32(c.w)))
+        return false;
+    return g2ToEip(G2.BASE.multiply(h3(s, m))).toLowerCase() === c.u.toLowerCase();
+}
+/** drand's signature on `round` (hex, 48 bytes), checked against the network's key. Null while the round is not out. */
+export async function fetchRoundSig(round, net = QUICKNET, fetcher = fetch) {
+    for (const base of net.urls) {
+        try {
+            const res = await fetcher(`${base}/${net.chainHash}/public/${round}`, { cache: "no-store" });
+            if (!res.ok)
+                continue;
+            const j = (await res.json());
+            if (Number(j.round) !== Number(round) || typeof j.signature !== "string")
+                continue;
+            if (!verifyRoundSig(round, j.signature, net))
+                continue;
+            return j.signature;
+        }
+        catch {
+            // next relay
+        }
+    }
+    return null;
+}

package/dist/tx.d.ts

@@ -66,5 +66,7 @@ export declare function sendTx(ctx: Ctx, tx: TxRequest, o?: SendOptions): Promis
 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

@@ -65,5 +65,14 @@ export async function sendAll(ctx, txs, o = {}) {
 }
 /** 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/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;
+}

package/dist/watch.d.ts

@@ -0,0 +1,82 @@
+import { type Address, type Hex } from "viem";
+import type { AgentsModule } from "./agents.js";
+import type { AnyModule } from "./any.js";
+import type { CoinsModule } from "./coins.js";
+import type { CallsModule, PoolsModule } from "./pools.js";
+import type { StickyModule } from "./sticky.js";
+import type { Ctx } from "./tx.js";
+/**
+ * Live events, for terminals and bots: every launch on the pad, every trade of a coin, everything that happens to an
+ * agent coin. Each watcher polls the RPC (HTTP is enough) and returns a function that stops it.
+ *
+ *   const stop = ph.watch.launches((l) => console.log(l.mode, l.symbol, l.token));
+ *   const stop2 = await ph.watch.trades(token, (t) => console.log(t.buy ? "buy" : "sell", t.bnb, t.coins));
+ *   const stop3 = await ph.watch.agent(token, (e) => console.log(e.event, e.args));
+ */
+export type WatchMode = "sticky" | "sticky2" | "rules" | "rules-v1" | "pools" | "calls" | "lever" | "agents" | "any";
+export type WatchedLaunch = {
+    mode: WatchMode;
+    token: Address;
+    creator: Address;
+    /** read from the token when `details` is on (default) */
+    name: string;
+    symbol: string;
+    /** the V3 pool and V2 pair (sticky, rules), the Infinity pool id (pools, calls, lever, agents, any) */
+    pool?: Address;
+    pair?: Address;
+    poolId?: Hex;
+    factory: Address;
+    block: bigint;
+    tx: Hex;
+    /** the raw event as viem decoded it */
+    args: Record<string, unknown>;
+};
+export type WatchedTrade = {
+    token: Address;
+    buy: boolean;
+    /** the trader where the event names one (the hooks do; V3 and V2 name the router's sender and the recipient) */
+    trader: Address | null;
+    /** coins moved (18 decimals), BNB moved (wei); the hooks' events carry the fee or the BNB, the pools' Swap both sides */
+    coins: bigint;
+    bnb: bigint | null;
+    /** the hook's fee in BNB (pools, calls, agents) */
+    fee: bigint | null;
+    /** v3, v2 (PancakeSwap pools of sticky and rules coins), or the hook's event (pools, calls, agents, any) */
+    source: "v3" | "v2" | "hook";
+    block: bigint;
+    tx: Hex;
+};
+export type AgentEvent = {
+    token: Address;
+    /** Proposed, Cancelled, Activated, Vetoed, VetoBacked, FireBacked, PilotFired, PilotHandedOver, Locked, Withdrawn, TreasuryMoved (desk); Burned, LiquidityAdded, FloorFed, Moved, Given, ProgramSet, JackpotWon, RewardEarned, Traded (hook) */
+    event: string;
+    args: Record<string, unknown>;
+    block: bigint;
+    tx: Hex;
+};
+export type WatchOptions = {
+    /** ms between polls (default 3000, about one BNB Chain block) */
+    pollingInterval?: number;
+    /** errors of the poll (an RPC hiccup); default: ignored, the next poll tries again */
+    onError?: (e: Error) => void;
+};
+type Mods = {
+    sticky: StickyModule;
+    sticky2: StickyModule;
+    coins: CoinsModule;
+    pools: PoolsModule;
+    calls: CallsModule;
+    agents: AgentsModule;
+    any: AnyModule;
+};
+export declare function watchModule(ctx: Ctx, mods: Mods): {
+    launches: (cb: (l: WatchedLaunch) => void, o?: WatchOptions & {
+        modes?: WatchMode[];
+        details?: boolean;
+    }) => () => void;
+    trades: (token: Address, cb: (t: WatchedTrade) => void, o?: WatchOptions) => Promise<() => void>;
+    agent: (token: Address, cb: (e: AgentEvent) => void, o?: WatchOptions) => Promise<() => void>;
+    modes: WatchMode[];
+};
+export type WatchModule = ReturnType<typeof watchModule>;
+export {};