@pickhooks/sdk 0.0.0-stage → 0.4.0

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 {};

package/dist/watch.js

@@ -0,0 +1,194 @@
+import { isAddressEqual, parseAbi } from "viem";
+import { agentsDeskAbi, agentsFactoryAbi, agentsHookAbi } from "./abis/agents.js";
+import { any3FactoryAbi, any3HookAbi } from "./abis/any3.js";
+import { callsFactoryAbi, callsHookAbi } from "./abis/calls.js";
+import { lever2FactoryAbi } from "./abis/lever2.js";
+import { poolsFactoryAbi, poolsHookAbi } 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";
+import { PickhooksError } from "./errors.js";
+const v3SwapAbi = parseAbi([
+    "event Swap(address indexed sender, address indexed recipient, int256 amount0, int256 amount1, uint160 sqrtPriceX96, uint128 liquidity, int24 tick, uint128 protocolFeesToken0, uint128 protocolFeesToken1)",
+]);
+const v2SwapAbi = parseAbi(["event Swap(address indexed sender, uint256 amount0In, uint256 amount1In, uint256 amount0Out, uint256 amount1Out, address indexed to)"]);
+const PLAIN = parseAbi(["function name() view returns (string)", "function symbol() view returns (string)"]);
+export function watchModule(ctx, mods) {
+    const { pub, a } = ctx;
+    const abs = (v) => (v < 0n ? -v : v);
+    const factories = [
+        { mode: "sticky", address: a.stickyFactory, abi: stickyFactoryAbi, event: "Launched" },
+        { mode: "sticky2", address: a.sticky2Factory, abi: sticky2FactoryAbi, event: "Launched" },
+        { mode: "rules", address: a.coinsV2Factory, abi: v2FactoryAbi, event: "Launched" },
+        { mode: "rules-v1", address: a.coinsV1Factory, abi: v1FactoryAbi, event: "Launched" },
+        { mode: "pools", address: a.poolsFactory, abi: poolsFactoryAbi, event: "Launched" },
+        { mode: "calls", address: a.callsFactory, abi: callsFactoryAbi, event: "Launched" },
+        { mode: "lever", address: a.lever2Factory, abi: lever2FactoryAbi, event: "Launched" },
+        { mode: "agents", address: a.agentsFactory, abi: agentsFactoryAbi, event: "Launched" },
+        { mode: "any", address: a.anyFactory, abi: any3FactoryAbi, event: "Opened" },
+    ];
+    const watch = (p, o) => pub.watchContractEvent({
+        address: p.address,
+        abi: p.abi,
+        eventName: p.eventName,
+        args: p.args,
+        onLogs: p.onLogs,
+        onError: o.onError ?? (() => undefined),
+        poll: true,
+        pollingInterval: o.pollingInterval ?? 3000,
+        strict: false,
+    });
+    /**
+     * Every new coin on the pad (and every new hook any coin pool), as it is mined. `modes` narrows it; `details` reads
+     * name and symbol from the token (one multicall per batch).
+     */
+    function launches(cb, o = {}) {
+        const wanted = factories.filter((f) => !isAddressEqual(f.address, ZERO_ADDRESS) && (!o.modes || o.modes.includes(f.mode)));
+        const stops = wanted.map((f) => watch({
+            address: f.address,
+            abi: f.abi,
+            eventName: f.event,
+            onLogs: async (logs) => {
+                const rows = logs.map((log) => {
+                    const args = (log.args ?? {});
+                    return {
+                        mode: f.mode,
+                        token: args.token,
+                        creator: (args.creator ?? args.opener),
+                        name: "",
+                        symbol: "",
+                        pool: args.pool,
+                        pair: args.pair,
+                        poolId: (args.poolId ?? args.id),
+                        factory: f.address,
+                        block: log.blockNumber ?? 0n,
+                        tx: log.transactionHash ?? "0x",
+                        args,
+                    };
+                });
+                if (o.details !== false && rows.length) {
+                    const meta = await pub
+                        .multicall({ contracts: rows.flatMap((r) => [{ address: r.token, abi: PLAIN, functionName: "name" }, { address: r.token, abi: PLAIN, functionName: "symbol" }]), allowFailure: true })
+                        .catch(() => null);
+                    if (meta)
+                        rows.forEach((r, i) => Object.assign(r, { name: meta[i * 2].status === "success" ? String(meta[i * 2].result) : "", symbol: meta[i * 2 + 1].status === "success" ? String(meta[i * 2 + 1].result) : "" }));
+                }
+                for (const r of rows)
+                    cb(r);
+            },
+        }, o));
+        return () => stops.forEach((s) => s());
+    }
+    /** The hooks' Traded(id, trader, buy, tokens, fee|bnb) for a set of pool ids on one hook. */
+    const hookTrades = (token, hook, abi, ids, bnbField, cb, o) => watch({
+        address: hook,
+        abi,
+        eventName: "Traded",
+        args: { id: ids },
+        onLogs: (logs) => {
+            for (const log of logs) {
+                const g = (log.args ?? {});
+                cb({
+                    token,
+                    buy: Boolean(g.buy),
+                    trader: g.trader ?? null,
+                    coins: g.tokens,
+                    bnb: bnbField === "bnb" ? g.bnb : null,
+                    fee: bnbField === "fee" ? g.fee : null,
+                    source: "hook",
+                    block: log.blockNumber ?? 0n,
+                    tx: log.transactionHash ?? "0x",
+                });
+            }
+        },
+    }, o);
+    /** A PancakeSwap V3 pool's and V2 pair's Swap events of a coin (sticky and rules coins trade there). */
+    const pancakeTrades = (token, pool, pair, cb, o) => {
+        // the coin is token0 when its address sorts under WBNB's
+        const coinIs0 = token.toLowerCase() < a.wbnb.toLowerCase();
+        const stops = [
+            watch({
+                address: pool,
+                abi: v3SwapAbi,
+                eventName: "Swap",
+                onLogs: (logs) => {
+                    for (const log of logs) {
+                        const g = (log.args ?? {});
+                        const coin = (coinIs0 ? g.amount0 : g.amount1);
+                        const bnb = (coinIs0 ? g.amount1 : g.amount0);
+                        // the pool's view: a negative coin amount left the pool, so someone bought
+                        cb({ token, buy: coin < 0n, trader: g.recipient ?? null, coins: abs(coin), bnb: abs(bnb), fee: null, source: "v3", block: log.blockNumber ?? 0n, tx: log.transactionHash ?? "0x" });
+                    }
+                },
+            }, o),
+        ];
+        if (!isAddressEqual(pair, ZERO_ADDRESS)) {
+            stops.push(watch({
+                address: pair,
+                abi: v2SwapAbi,
+                eventName: "Swap",
+                onLogs: (logs) => {
+                    for (const log of logs) {
+                        const g = (log.args ?? {});
+                        const coinOut = (coinIs0 ? g.amount0Out : g.amount1Out);
+                        const coinIn = (coinIs0 ? g.amount0In : g.amount1In);
+                        const bnbOut = (coinIs0 ? g.amount1Out : g.amount0Out);
+                        const bnbIn = (coinIs0 ? g.amount1In : g.amount0In);
+                        const buy = coinOut > 0n;
+                        cb({ token, buy, trader: g.to ?? null, coins: buy ? coinOut : coinIn, bnb: buy ? bnbIn : bnbOut, fee: null, source: "v2", block: log.blockNumber ?? 0n, tx: log.transactionHash ?? "0x" });
+                    }
+                },
+            }, o));
+        }
+        return () => stops.forEach((s) => s());
+    };
+    /**
+     * Every trade of a pickhooks coin, whatever its mode: the hook's Traded events (pools, calls, agents, hook any coin
+     * pools next to the coin) or the Swap events of its PancakeSwap V3 pool and V2 pair (sticky, rules).
+     */
+    async function trades(token, cb, o = {}) {
+        if (await mods.agents.isCoin(token))
+            return hookTrades(token, await mods.agents.hook(), agentsHookAbi, [(await mods.agents.coin(token)).id], "fee", cb, o);
+        if (await mods.pools.isCoin(token))
+            return hookTrades(token, await mods.pools.hook(), poolsHookAbi, [(await mods.pools.coin(token)).id], "fee", cb, o);
+        if (await mods.calls.isCoin(token))
+            return hookTrades(token, await mods.calls.hook(), callsHookAbi, [(await mods.calls.coin(token)).id], "fee", cb, o);
+        for (const s of [mods.sticky, mods.sticky2]) {
+            if (await s.isCoin(token).catch(() => false)) {
+                const c = (await s.coin(token));
+                return pancakeTrades(token, c.pool, c.pair, cb, o);
+            }
+        }
+        if (await mods.coins.versionOf(token).catch(() => null)) {
+            const c = (await mods.coins.coin(token));
+            return pancakeTrades(token, c.pool, c.pair, cb, o);
+        }
+        const pools = await mods.any.poolsOf(token).catch(() => []);
+        if (pools.length) {
+            const stops = [...new Set(pools.map((p) => p.hook.toLowerCase()))].map((h) => hookTrades(token, h, any3HookAbi, pools.filter((p) => p.hook.toLowerCase() === h).map((p) => p.id), "bnb", cb, o));
+            return () => stops.forEach((s) => s());
+        }
+        throw new PickhooksError("This is not a coin pickhooks knows.", { code: "input" });
+    }
+    /** Everything that happens to an agent coin: the desk's events (changes, vetoes, firing, treasury moves) and the hook's runs. */
+    async function agent(token, cb, o = {}) {
+        if (!(await mods.agents.isCoin(token)))
+            throw new PickhooksError("This is not an agent coin.", { code: "input" });
+        const [hook, desk, c] = await Promise.all([mods.agents.hook(), mods.agents.desk(), mods.agents.coin(token)]);
+        const emit = (logs) => {
+            for (const log of logs) {
+                const l = log;
+                cb({ token, event: l.eventName ?? "", args: l.args ?? {}, block: log.blockNumber ?? 0n, tx: log.transactionHash ?? "0x" });
+            }
+        };
+        const stops = [
+            watch({ address: desk, abi: agentsDeskAbi, args: { token }, onLogs: emit }, o),
+            watch({ address: hook, abi: agentsHookAbi, args: { token }, onLogs: emit }, o),
+            watch({ address: hook, abi: agentsHookAbi, eventName: "Traded", args: { id: c.id }, onLogs: emit }, o),
+        ];
+        return () => stops.forEach((s) => s());
+    }
+    return { launches, trades, agent, modes: factories.filter((f) => !isAddressEqual(f.address, ZERO_ADDRESS)).map((f) => f.mode) };
+}

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "@pickhooks/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.0",
+  "description": "Read, quote, trade and launch on pickhooks (BNB Chain) from a bot, a launchpad or a trading terminal. Built on viem.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./abis": {
+      "types": "./dist/abis/index.d.ts",
+      "import": "./dist/abis/index.js"
+    },
+    "./rules": {
+      "types": "./dist/sticky-rules.d.ts",
+      "import": "./dist/sticky-rules.js"
+    },
+    "./coin-rules": {
+      "types": "./dist/coin-rules.d.ts",
+      "import": "./dist/coin-rules.js"
+    },
+    "./tlock": {
+      "types": "./dist/tlock.d.ts",
+      "import": "./dist/tlock.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "abis": "node scripts/gen-abis.mjs",
+    "build": "node scripts/gen-abis.mjs && tsc -p tsconfig.json",
+    "check": "node scripts/check-rules-copy.mjs",
+    "test": "node --test test/unit.test.mjs",
+    "fork-proof": "node test/fork-proof.mjs",
+    "fork-proof-2": "node test/fork-proof-2.mjs",
+    "fork-proof-infra": "node test/fork-proof-infra.mjs",
+    "mainnet-read-agents": "node test/mainnet-read-agents.mjs",
+    "release": "node scripts/publish.mjs"
+  },
+  "dependencies": {
+    "@noble/curves": "^1.9.1",
+    "@noble/hashes": "^1.8.0"
+  },
+  "peerDependencies": {
+    "viem": "^2.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "viem": "^2.57.2"
+  },
+  "keywords": [
+    "pickhooks",
+    "bnb-chain",
+    "pancakeswap",
+    "infinity",
+    "hooks",
+    "viem"
+  ],
+  "engines": {
+    "node": ">=20"
+  }
+}