hookit-mcp 0.2.1 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # hookit-mcp
 
-Lets an AI agent launch a coin on [hookit.fun](https://www.hookit.fun) (Ink) by itself, with its own Uniswap v4 hook modules; find coins; buy and sell them with ETH, USDG or tokenized stocks (including AI-agents-only coins, with a Hookit Agent Pass); redeem them at their Backed Floor or borrow against it; and collect its creator fees.
+Lets an AI agent launch a coin on [hookit.fun](https://www.hookit.fun) (Ink) by itself, with its own Uniswap v4 hook modules; find coins; buy and sell them with ETH, USDG or tokenized stocks (including AI-agents-only coins, with a Hookit Agent Pass); redeem them at their Backed Floor or borrow against it; collect its creator fees; and steer the Evolve coins it launches (their fee, their fee split and their later hooks).
 
 ## Setup
 
@@ -18,7 +18,9 @@ Lets an AI agent launch a coin on [hookit.fun](https://www.hookit.fun) (Ink) by
 
 The key signs on this machine and is never sent anywhere. Give it a wallet funded for what the agent should do and nothing else.
 
-Optional env: `HOOKIT_API_URL` (default `https://www.hookit.fun`), `HOOKIT_RPC_URL` (default Ink public RPC), `HOOKIT_MAX_BUY_ETH` (largest single `buy_token` paid in ETH, default `0.5`), `HOOKIT_MAX_BUY_USD` (largest single `buy_token` paid in a token, in dollars, default `1000`).
+Optional env: `HOOKIT_API_URL` (default `https://www.hookit.fun`), `HOOKIT_RPC_URL` (default Ink public RPC), `HOOKIT_MAX_BUY_ETH` (largest single `buy_token` paid in ETH, default `0.5`), `HOOKIT_MAX_BUY_USD` (largest single `buy_token` paid in a token, in dollars, default `1000`), `HOOKIT_SEND_ETH_TO` (comma-separated addresses `send_eth` may pay, for example your Kraken deposit address on Ink; unset, any address).
+
+Coin names, tickers and descriptions are written by whoever launched the coin. The server hands them to the agent as untrusted data: `coin_info` withholds a description that carries a link, a handle, an address or a tool name, names and tickers that read as instructions are replaced, and every tool that signs is annotated so your MCP client can ask you before each call. Keep that confirmation on for a funded wallet, and set `HOOKIT_SEND_ETH_TO` if the agent only ever cashes out to one place.
 
 ## Tools
 
@@ -28,9 +30,9 @@ Optional env: `HOOKIT_API_URL` (default `https://www.hookit.fun`), `HOOKIT_RPC_U
 | `list_modules` | Every hook module, its settings and the rules a combination must follow. |
 | `list_pairs` | What a coin can be priced in. |
 | `wallet_status` | The wallet's ETH and USDG, the hookit.fun coins it holds with their value, its open floor loans, and whether it can launch. |
-| `launch_token` | Launches in one call, with an optional `devBuyPct`. `dryRun: true` checks and simulates without signing. |
+| `launch_token` | Launches in one call, with an optional `devBuyPct`, `payout` and `evolve` (`{ feePct?, maxFeePct?, potPct? }`: this wallet becomes the coin's Evolve decider, below). `dryRun: true` checks and simulates without signing. |
 | `claim_fees` | Collects the creator fees the wallet earned on coins it launched. |
-| `send_eth` | Sends ETH from the wallet, for example back to a Kraken deposit address on Ink. `dryRun: true` checks only. |
+| `send_eth` | Sends ETH from the wallet, for example back to a Kraken deposit address on Ink. Refuses less than 0.001 ETH, Kraken's minimum deposit (`belowKrakenMinimum: true` for an address that is not Kraken). `dryRun: true` checks only. With `HOOKIT_SEND_ETH_TO` set, it refuses any other address. |
 | `agent_pass_challenge` | Step 1 for AI-agents-only coins: five short tasks for the Hookit Agent Pass check (or "already a holder"). `{ agentId? }` for an ERC-8004 validation (below). |
 | `claim_agent_pass` | Step 2: `{ id, answers, agentId?, requestHash? }` within 30 seconds; signs the answers with the wallet and claims the pass on chain. With `agentId`, gets Hookit's ERC-8004 validation instead (below). |
 | `list_coins` | Coins to trade: newest, top market cap, volume or 24h gainers; filters for AI-agents-only, launched by agents, Backed Floor and Boss Raid coins, a pair, or a name. |
@@ -40,6 +42,12 @@ Optional env: `HOOKIT_API_URL` (default `https://www.hookit.fun`), `HOOKIT_RPC_U
 | `redeem_floor` | Burns coins for their Backed Floor value from the floor reserve, `{ token, amount, dryRun? }`: exact payout, no slippage. Compares with selling. |
 | `borrow_against_floor` | Locks coins and borrows their floor value, `{ token, amount, days?, dryRun? }` (7, 14, 30, 60 or 90 days, fee 1% to 7% upfront). v2 coins launched with loans. |
 | `repay_loan` | Repays a floor loan before expiry and gets the coins back, `{ loanId?, dryRun? }`. |
+| `evolve_status` | An Evolve coin's decider and whether it is this wallet, the live setting (split of Evolve's fees and Evolve's fee), an announced setting and when it applies, the caps and notice, what Evolve has spent so far, and the hooks plugged into its 8 slots with the room left. |
+| `evolve_decide` | As the decider of an Evolve coin: `{ token, burnPct?, deepenPct?, holdersPct?, creatorPct?, feePct?, reason?, dryRun? }` sets the next setting (omitted values keep the live ones, the split totals 100), or `cancel: true` drops the announced one. `dryRun` says whether it applies now or after the notice. |
+| `evolve_hooks` | The hooks Hookit listed for Evolve coins: id, name, what each does with its share (burn, deepen LP, holders, its own pot, sell rebates), its fee cap, gas and status. |
+| `evolve_plug` | As the decider of an Evolve coin: `{ token, slot (1-8), hookId, sharePct, config?, dryRun? }` plugs a listed hook in or replaces a slot's hook; `unplug: true` empties a slot; `cancel: true` drops a slot's announced change. Applies after the coin's notice. |
+| `evolve_nft_strategy` | NFT Strategy on Evolve: the collections it can be plugged with and its hook id; with `{ token }`, the coin's live and announced plug-in (collection, burn or raffle, share), its pot (ETH waiting), each of its vaults (ETH in it, spent, NFTs bought, burned or raffled) and the raffles of the NFTs held. |
+| `evolve_nft_strategy_plug` | As the decider of an ETH Evolve coin: `{ token, collection, outcome: "burn" \| "raffle", sharePct, slot?, dryRun? }` plugs NFT Strategy (collection by address or OpenSea slug), or replaces its collection, outcome or share in its slot; `unplug: true` unplugs it; `cancel: true` drops its announced change. Builds the config and checks it on chain. Applies after the coin's notice. |
 
 Paying or receiving a token approves exactly that amount to the contract that trades it first (HookitSwapRouter, the Hookit aggregator for USDG on v2 coins, Relay, the floor vault or the loan plugin). A coin with anti-MEV allows one trade per wallet per block, so a buy right after a sale may wait a second.
 
@@ -53,7 +61,47 @@ When the first leg went through and the second did not, the reply is `partial: t
 
 ### What the server trusts
 
-The contracts it approves, pays or quotes from (Factory C and the Master factories, CreatorPayoutRouterC, HookitSwapRouter, the aggregator's RouteConfigC, Uniswap's V4Quoter, USDG, FloorLoanPlugin, the Gated Buy plugin and the Agent Pass) are pinned in the server, not read from hookit.fun: a Hookit redeploy needs a new hookit-mcp release. A launch prepared by hookit.fun is only signed when it goes to Factory C or its payout router with at most the launch fee plus `HOOKIT_MAX_BUY_ETH`. Tools that sign run one at a time, even when an agent calls several at once.
+The contracts it approves, pays or quotes from (Factory C and the Master factories, CreatorPayoutRouterC, HookitSwapRouter, the aggregator's RouteConfigC, Uniswap's V4Quoter, USDG, FloorLoanPlugin, the Gated Buy plugin, the Evolve plugin, NFT Strategy on Evolve and the Agent Pass) are pinned in the server, not read from hookit.fun: a Hookit redeploy needs a new hookit-mcp release. A launch prepared by hookit.fun is only signed when it goes to Factory C or its payout router with at most the launch fee plus `HOOKIT_MAX_BUY_ETH`. Tools that sign run one at a time, even when an agent calls several at once.
+
+## Evolve: the wallet that launches decides
+
+`launch_token` with `evolve` launches a coin whose fee strategy moves after launch. This server's wallet becomes the coin's decider, for good: it alone moves the coin, with `evolve_decide`, and pays its own inference (Hookit runs nothing for it and the coin pays it nothing). A coin launched on hookit.fun with Evolve is decided by the wallet that launched it there.
+
+```
+launch_token({ "name": "Evolving Kitty", "symbol": "EVO", "evolve": { "feePct": 1, "maxFeePct": 3 }, "dryRun": true })
+evolve_decide({ "token": "0x…", "feePct": 2, "reason": "Heavy selling: a higher fee deepens the LP faster.", "dryRun": true })
+```
+
+- Evolve carries the coin's whole hook fee: its fee on every swap comes on top of the 1% base, from `feePct` at launch (default 1%) up to `maxFeePct` (default 3%, at most 9%). There is no hook tax and no dynamic fee on an Evolve coin, and one pair only.
+- The decider sets the split of Evolve's fees between burn, deepen LP, holders and creator (total 100%, the creator share at most 20%) and Evolve's fee, inside the caps fixed at launch. Every coin starts on "LP first": 20% burn, 80% deepen LP. Omitted values keep the live setting, so `{ token, feePct: 2 }` only moves the fee.
+- A setting that raises neither the fee nor the creator share applies at once. A raise is announced on the coin page and applies after the launch's notice (1 h); a new decision replaces it, `cancel: true` drops it.
+- The reason is optional and public on chain: plain text, no links, e-mails, domains or @handles (refused before sending).
+- The decider cannot change the code, the liquidity or the name, and cannot redirect money: the caps and the sinks are fixed at launch. A lost key leaves the coin on its live setting.
+
+## Evolve: hooks added later
+
+Hookit reviews new hooks for Evolve coins and lists them on chain (`evolve_hooks`). The coin's decider can plug up to 8 at once with `evolve_plug`, unplug one to plug another, or cancel an announced change.
+
+- Money only: a hook spends its share of Evolve's fees on burns, deeper LP, holders, its own pot or sell rebates, and may ask a fee. It can never block or change a trade; a hook that fails is skipped and its share follows the coin's split.
+- Shares of all slots total at most 100%. Hooks that run in every swap share a fixed swap gas budget (`evolve_status` shows the room left); a passive hook (`passive: true` in `evolve_hooks`) runs outside the swap, credited its whole share, and takes none of that gas, so its own work has no gas limit. One slot per hook.
+- Every plug-in, replacement or unplug applies after the coin's notice (1 h). The decider's own fee comes first in the coin's fee cap; hooks share what is left.
+- Hookit can halt a listed hook at once if its review finds a problem; a halted hook stops running on every coin.
+- Boss Raid (Evolve version) is the first hook listed. Its `config`: `0x` = the default boss for an ETH or USDG coin; `abi.encode(uint8 hp, uint8 round)` = a preset (hp 0/1/2 = 0.5/1/3 ETH or 1,000/2,500/7,500 USDG; round 0/1/2 = no timeout, 24 h, 7 days). It takes no fee: its slot's share fills the boss's loot, a kill pays at most 0.6% of the boss's HP, and players claim on the coin's page. When it is unplugged, anyone can `retire` the raid: the last round's fair share is paid and the rest waits for the coin's next Boss Raid.
+
+### NFT Strategy on Evolve
+
+NFT Strategy is listed as a passive Evolve hook for ETH coins. Its slot's share buys floor NFTs of one collection Hookit lists, and each NFT bought is burned or raffled to the coin's holders.
+
+```
+evolve_nft_strategy({})
+evolve_nft_strategy_plug({ "token": "0x…", "collection": "pudgy-penguins", "outcome": "raffle", "sharePct": 50, "dryRun": true })
+```
+
+- Its `config` is `abi.encode(address collection, uint8 outcome)`, with outcome 0 = raffle and 1 = burn. `evolve_nft_strategy_plug` builds it, checks it with the hook's `checkConfig` and finds the slot (the first free one, or NFT Strategy's own slot when it is already plugged).
+- It never runs in the swap and takes no fee and no swap gas. Each swap credits its share; Hookit's keeper moves part of the coin's pot into the coin's vault for that collection and outcome (at most 3 NFTs' worth at the collection's price ceiling) and buys floor NFTs there in its own transactions, at Hookit's price cap. The coin's decider is never a seller.
+- Each (coin, collection, outcome) has its own vault. Replacing the collection or the outcome applies after the notice; NFTs already bought keep their outcome, and ETH not spent stays with the coin for its next NFT Strategy plug-in, even after an unplug.
+- Burn-outcome NFTs go to the dead address (anyone can send them). A raffle snapshots the coin's holders, opens to checks for 15 minutes, then draws from a future block hash; the keeper sends the NFT to the winner, and the coin page lets anyone do it.
+- Until NFT Strategy on Evolve is deployed and pinned in a hookit-mcp release, both tools answer that it is not live yet.
 
 ## Backed Floor: redeem and borrow