@pickhooks/sdk 0.4.0 → 0.5.0

package/README.md

@@ -306,6 +306,36 @@ const o = await ph.dark.opener(roundId);              // once drand signed: the
 
 The seal is time-lock encryption to drand quicknet, the same scheme as find the dev. `@pickhooks/sdk/tlock` holds it on its own entry (`encrypt`, `decrypt`, `darkMessage`, `fetchRoundSig`, `roundAt`), so the main import does not load BLS12-381.
 
+## sticky 3, games inside the coin: `ph.sticky3`, `ph.modes`, `ph.simulate`
+
+A sticky 3 coin is a sticky 2 coin with a **mode**: a game contract fixed at launch that the coin calls on every buy, sell and send, that holders play through the coin (`play`) and that anyone nudges (`poke`). The modes:
+
+- **combo**: buys build the combo, one sell breaks it; the 10th, 25th and 50th buy in a row win part of the pot.
+- **pay it forward**: a share of every buy goes to the wallet that bought before.
+
+What the coin holds whatever a mode does: every terminal trades it from the first second; sells and sends are never taxed and a buy gives at most 10 % to burns and pots together; the game pot moves only by the mode's orders; custody always ends by itself (at most 7 days; 14 for a dev bag locked at the launch); a mode that fails or runs out of its 250,000 gas is skipped and the trade stands; the mode is fixed for good.
+
+```js
+// a coin with a game
+const { token } = await ph.sticky3.launch({ name, symbol, metadata, picks: [{ id: "sniper" }], mode: "combo", modeSettings: { bps: 200 }, devBuy: parseEther("0.05") });
+
+// or from one sentence (pass a reader, your model, for what the parser does not understand)
+const r = await ph.sticky3.fromText("CAT Cat, combo 3 %, dev lock 7 days, sniper jail, dev buy 0.05", { metadata });
+if (r.launch) await ph.sticky3.launch(r.launch);
+
+ph.modes.list;                                        // the modes: line, how it plays, share of buys and bounds, moves
+await ph.modes.of(token);                             // { name, gameBps, gamePot, info }
+await ph.modes.combo.state(token);                    // every mode has state()
+await ph.modes.custody(token, wallet);                // coins in custody, until, releasable
+
+const s = await ph.simulate.buy({ token, wallet, bnbIn: parseEther("0.05") });
+// { ok, out, burned, toPots, gamePot: { before, after }, bonus, intoCustody, paidOthers, events, gas } or { ok: false, refused }
+await ph.simulate.sell({ token, wallet, amount });
+await ph.simulate.send({ token, wallet, to, amount });
+```
+
+`ph.simulate` runs any trade or move on the chain as it is now (eth_simulateV1, on BNB Chain's public RPC and most providers): what arrives, what burns, what goes into the pots, what the game pays this wallet or others, what goes into custody, the mode's events as sentences, or the rule that stops it. The sticky 3 factory and the modes are zero in `BSC_MAINNET` until they are on mainnet; on a fork pass `addresses` (`sticky3Factory`, `sticky3Lens`, `drandBeacon`, `modes`). A terminal can do all of it from a shell with the CLI: `npx pickhooks`.
+
 ## Agents: `ph.agents`
 
 On mainnet since 09.10.2026 (factory `0x5965e2D2128248ac2CB4FFf312CFB098a1eDA232`). An agent coin is a plain ERC20 in a PancakeSwap Infinity pool whose hook runs a **program**: the fee on each side (1 % up to the coin's cap), where the coin's part of every fee goes (burn, liquidity the coin owns for good, its HOOKS floor, a rewards pot, a jackpot, the creator, the treasury) and up to eight pool rules. The **pilot** (any wallet: the pickhooks agent, your bot, a model behind an MCP server) proposes a whole new program; the desk checks it against the coin's **envelope** (limits fixed for good at launch: max fee, max creator share, allowed rules, notice, gap, veto and fire shares) and the limits every agent coin lives with (sells can never be closed for good, no rule names a wallet, BNB never leaves the coin). The change is announced and lands after the notice; holders lock coins to **veto** it or to **fire** the pilot. Every router trades the coin.
@@ -404,7 +434,7 @@ Every failure is a `PickhooksError` with `code` (the contract's error name, or `
 | the pickhooks agent (pilot wallet) | `0x85b85b75806446BB7AFa324D67B20cc1C29eCFB5` |
 | $hooks | `0x07bcB8E8226f671300e135b4A61Dc157359b7777` |
 
-All verified on BscScan. `BSC_MAINNET` holds these and PancakeSwap's; `createPickhooks({ addresses })` points the SDK elsewhere (a fork). The tax line's factory is not set yet (`anyTaxFactory` is zero until it is on mainnet). ABIs: `@pickhooks/sdk/abis`; the drand time-lock: `@pickhooks/sdk/tlock`; the sticky encoder alone: `@pickhooks/sdk/rules`; the rule catalog of coins with rules: `@pickhooks/sdk/coin-rules`.
+All verified on BscScan. `BSC_MAINNET` holds these and PancakeSwap's; `createPickhooks({ addresses })` points the SDK elsewhere (a fork). The tax line's factory is not set yet (`anyTaxFactory` is zero until it is on mainnet), nor sticky 3 (`sticky3Factory`, `modes`). ABIs: `@pickhooks/sdk/abis`; the drand time-lock: `@pickhooks/sdk/tlock`; the sticky encoder alone: `@pickhooks/sdk/rules`; the rule catalog of coins with rules: `@pickhooks/sdk/coin-rules`.
 
 ## Examples
 
@@ -416,4 +446,4 @@ They send nothing without `--send`.
 
 ## Tests
 
-`npm test` (offline: pool ids, ranges, building, errors, the rule compiler, the time-lock against the site's copy). On a local BSC fork (`scripts/fork.sh`, anvil) against the live contracts: `npm run fork-proof` (hook any coin and sticky rules) and `npm run fork-proof-2` (coins with rules, pools, dip bids, Lever, lever v1, curve calls, and the tax line, which it deploys on the fork from a throwaway key). `npm run fork-proof-infra` runs floors and the protected buy on the infra rehearsal fork (`script/infra/rehearsal-fork.sh`, contracts deployed there by a throwaway key) against a dev server of the site. `npm run check` confirms the rule catalogs and the building blocks catalog are the site's, and that the agents catalog and the pilot's prompt behave like the site's and the keeper's. `node test/mainnet-read-agents.mjs` reads the agents, watch and wallet parts against mainnet (nothing sent); the fork proof of those parts lives with the MCP server (`mcp/test/fork-proof-agents.mjs`: launch, trades, a model's answer landing through the desk, veto, fire, the watchers seeing it all).
+`npm test` (offline: pool ids, ranges, building, errors, the rule compiler, the time-lock against the site's copy). On a local BSC fork (`scripts/fork.sh`, anvil) against the live contracts: `npm run fork-proof` (hook any coin and sticky rules) and `npm run fork-proof-2` (coins with rules, pools, dip bids, Lever, lever v1, curve calls, and the tax line, which it deploys on the fork from a throwaway key). `npm run fork-proof-infra` runs floors and the protected buy on the infra rehearsal fork (`script/infra/rehearsal-fork.sh`, contracts deployed there by a throwaway key) against a dev server of the site. `npm run fork-proof-sticky3` runs sticky 3 on a fork where `script/sticky3/fork-deploy.sh` deployed it: a launch with every mode, trades through V3 and V2, simulations, the moves of every game, real drand rounds for the modes that draw. `npm run check` confirms the rule catalogs and the building blocks catalog are the site's, and that the agents catalog and the pilot's prompt behave like the site's and the keeper's. `node test/mainnet-read-agents.mjs` reads the agents, watch and wallet parts against mainnet (nothing sent); the fork proof of those parts lives with the MCP server (`mcp/test/fork-proof-agents.mjs`: launch, trades, a model's answer landing through the desk, veto, fire, the watchers seeing it all).

package/dist/abis/index.d.ts

@@ -11,4 +11,5 @@ export { callsDeskAbi, callsFactoryAbi, callsHookAbi } from "./calls.js";
 export { dipDeskAbi } from "./dips.js";
 export { hooksExecutorAbi, hooksFloorAbi, hooksFloorFactoryAbi } from "./infra.js";
 export { agentsDeskAbi, agentsFactoryAbi, agentsHookAbi } from "./agents.js";
+export { comboModeAbi, drandBeaconAbi, forwardModeAbi, sticky3FactoryAbi, sticky3LensAbi, sticky3TokenAbi, sticky3ValidatorAbi, } from "./sticky3.js";
 export { POOL_KEY, SWAP_EXACT_IN_SINGLE, clPoolManagerAbi, clQuoterAbi, erc20Abi, permit2Abi, universalRouterAbi, pancakeV2FactoryAbi, v2PairAbi, v3PoolAbi, v3QuoterAbi, v3RouterAbi, } from "./common.js";

package/dist/abis/index.js

@@ -11,4 +11,5 @@ export { callsDeskAbi, callsFactoryAbi, callsHookAbi } from "./calls.js";
 export { dipDeskAbi } from "./dips.js";
 export { hooksExecutorAbi, hooksFloorAbi, hooksFloorFactoryAbi } from "./infra.js";
 export { agentsDeskAbi, agentsFactoryAbi, agentsHookAbi } from "./agents.js";
+export { comboModeAbi, drandBeaconAbi, forwardModeAbi, sticky3FactoryAbi, sticky3LensAbi, sticky3TokenAbi, sticky3ValidatorAbi, } from "./sticky3.js";
 export { POOL_KEY, SWAP_EXACT_IN_SINGLE, clPoolManagerAbi, clQuoterAbi, erc20Abi, permit2Abi, universalRouterAbi, pancakeV2FactoryAbi, v2PairAbi, v3PoolAbi, v3QuoterAbi, v3RouterAbi, } from "./common.js";