hookit-mcp 0.3.0 → 0.4.0

package/README.md

@@ -18,7 +18,7 @@ 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`), `HOOKIT_SEND_ETH_TO` (comma-separated addresses `send_eth` may pay, for example your Kraken deposit address on Ink; unset, any address).
+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), `HOOKIT_MEMORY_EVOLVE` / `HOOKIT_MEMORY_LENS` / `HOOKIT_MEMORY_FEE1` / `HOOKIT_MEMORY_FEE2` (override Memory on Evolve's pinned addresses).
 
 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.
 
@@ -48,6 +48,10 @@ Coin names, tickers and descriptions are written by whoever launched the coin. T
 | `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. |
+| `memory_status` | Memory on an Evolve coin, `{ token }`: each Memory plug-in (slot, key, share, live or announced), its live rules in plain words with the moments running now and until when, an announced setup and when it goes live, its allies, fee cap and bot threshold; its fee companions and the plug-in each follows (companions ask while Memory runs the plug-in they follow); how far the fee can reach on the next trade; the cashback ledger (booked per plug-in, released to Memory, claimed, still waiting in Evolve); the plug-in Memory runs, the newest, the one pardons and registrations act on, and whether the one Memory runs retired. Each rule comes with its `memory_set` input. |
+| `memory_set` | As the decider of an Evolve coin that is an AI agent: `{ token, rules, allies?, feeCapPct?, botTrades?, reason?, sharePct?, slot?, dryRun? }` writes the coin's Memory setup (at most 8 rules, 3 allies). Plugs Memory first when it is not on the coin (lowest free slot, all the share left by default, after the notice) with the 0 to 2 fee companions its fee needs; otherwise edits the plug-in in Memory's slot (the newest one there) with the whole new setup, live at once when it is a cut, else after the notice, and plugs or unplugs companions to match. `cancel: true` drops an announced setup. Several transactions may be needed: `dryRun` (on unless `false`) lists and simulates them all. |
+| `memory_wallet` | What Memory knows of a wallet on a coin (on the plug-in Memory runs, else the newest), `{ token, wallet? }`: friend or enemy and until when, neutral (a shared signer: no give-back) or not, trades today, holding clock, open buys, cashback to claim, and which live rules apply to it now. |
+| `memory_pardon` | As the decider of a coin that runs or ran Memory: `{ token, wallets (at most 100), dryRun? }` clears the running enemy status of those wallets at once, whichever plug-in gave it (the others are left out). `dryRun` is on unless `false`. |
 
 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.
 
@@ -61,7 +65,7 @@ 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, 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.
+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 and Memory 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
 
@@ -103,6 +107,32 @@ evolve_nft_strategy_plug({ "token": "0x…", "collection": "pudgy-penguins", "ou
 - 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.
 
+### Memory on Evolve
+
+Memory is an Evolve hook for coins run by an AI agent: the coin's decider must own an ERC-8004 identity or hold the Hookit Agent Pass (checked at plug-in). The decider writes up to 8 rules, "for [who], when [moment], then [actions], for [duration]", and Memory applies them inside every trade, without the agent. It remembers the market, every wallet that trades the coin (the transaction's signer) and the agent's ally coins.
+
+```
+memory_set({ "token": "0x…", "rules": [
+  { "when": "sell_impact", "side": "sells", "thresholdPct": 4, "route": "burn", "mark": "enemy", "markMinutes": 1440 },
+  { "who": "enemies", "feePct": 3 },
+  { "who": "holders", "heldMinutes": 10080, "givebackPct": 2 },
+  { "who": "flippers", "resoldPct": 50, "withinMinutes": 10, "feePct": 2 }
+], "feeCapPct": 3 })
+memory_status({ "token": "0x…" })
+memory_wallet({ "token": "0x…", "wallet": "0x…" })
+```
+
+- Who: `anyone`, `friends` (a friend status from the rules, or holding an ally coin's `minBalance`), `enemies` (an enemy status from the rules), `flippers` (a sell that resells `resoldPct` of the wallet's open buys within `withinMinutes` of its last buy; sells only), `holders` (held the coin `heldMinutes`, 60 to 43,200; the clock starts at the first buy, or with "Start my holding clock" on the coin page), `non_enemies`. `side` is `buys`, `sells` or `both`; `minAmount` skips smaller trades.
+- When: `always` (every trade), `sell_impact`, `big_buy`, `price_drop`, `volume`, `silence`, `while_active` (Reflex's moments: `thresholdPct`, `amount`, `windowMinutes`, `whileRule`), in effect from the trade that triggers it to `durationMinutes` after (0 to 60; 0: that trade only).
+- Then: `feePct` (anyone, enemies or flippers only, at most 4 rules with a fee), `givebackPct` (0.01 to 10, never for enemies or flippers: a rebate inside an exact-input sell, else cashback the wallet claims on the coin page), `route` (Memory's share of the trade to `burn`, `lp` or `holders`), `mark` (`enemy` for 1 to 1,440 minutes, `friend` for 60 to 43,200). Statuses come only from the rules; the decider can only pardon (`memory_pardon`).
+- `feeCapPct` (0 to 3) caps the rules' fees added up on one trade. Evolve caps each hook's fee at 1%, so a cap above 1% runs Memory plus one or two fee companions (MemoryFee rank 1 asks the 2nd percent, rank 2 the 3rd), each fee-only, with share 0, in its own slot above Memory's. A companion follows the Memory plug-in in a slot below its own when it is plugged (the announced one if that slot has a change pending, else the live one), so `memory_set` plugs, re-plugs or unplugs them with Memory: one setup can take up to 3 transactions. Companions ask while Memory runs the plug-in they follow: the one Memory ran the coin's last trade for (before any trade, the newest). So during a re-plug's notice the old plug-in and its companions keep charging, the new plug-in's companions ask from its first trade, and after a cancelled re-plug Memory keeps running the live one. Once the plug-in Memory runs has left the slots, its companions keep asking until they are unplugged too (`evolve_plug` says so when Memory leaves), until another Memory plug-in trades, or until anyone calls `retire(token)` on Memory; `memory_status` warns when this happens.
+- `botTrades` (5 to 1,000, default 100): a wallet trading more than that in a UTC day becomes neutral for good (a shared signer: solvers, bundlers). A neutral wallet gets no give-back (no rebate, no cashback) and no new status; it meets the `anyone` and `non_enemies` rules (fees and routes), and the `enemies` ones while a grudge it had before turning neutral runs out (at most 24 h).
+- Holding clock: it starts at a wallet's first buy (or with "Start my holding clock", `register(token)`, for a wallet that holds the coin), stops when a sell leaves it under one unit (0.0001 of the quote, at that trade's price), and a clock started on less restarts at the wallet's next buy.
+- Pardons, registrations and `memory_wallet` act on the plug-in Memory runs (unless it retired, then on the newest); `memory_pardon` clears any running grudge on the coin, whichever plug-in gave it.
+- Editing: `memory_set` sends the whole setup (`memory_status` gives the live one as input). A cut is live at once and keeps the running moments: the same allies and `botTrades`, a cap no higher, and in place a fee lowered, a give-back raised, a route switched, an enemy mark shortened or dropped; rules without a route, give-back or friend mark dropped from the end; rules without a fee or mark appended. Anything else waits the coin's notice and restarts every moment. `dryRun` says which, before anything is sent.
+- Its `config` for `evolve_plug` is `abi.encode(Setup)`, `Setup = (Rule[] rules, (address coin, uint96 minBalance)[] allies, uint16 feeCap, uint16 botTrades)` with `Rule = (uint8 who, uint8 side, uint16 whoBps, uint32 whoWindow, uint128 minNotional, uint8 condition, uint32 window, uint128 threshold, uint16 duration, uint8 route, uint16 feeBps, uint16 perkBps, uint8 mark, uint32 markFor)`; its companions take `0x`. `memory_set` builds it, checks the bounds and the allies, and refuses a decider that is not an agent before anything is sent.
+- Memory's predicted addresses are pinned (list `c-evolve-memory`); until its contracts are deployed there, the four tools answer that it is not live yet. `HOOKIT_MEMORY_EVOLVE`, `HOOKIT_MEMORY_LENS`, `HOOKIT_MEMORY_FEE1` and `HOOKIT_MEMORY_FEE2` override them; nothing is used until code is there and the contracts point at each other.
+
 ## Backed Floor: redeem and borrow
 
 A coin launched with Backed Floor has a reserve that pays a floor price, reserve divided by circulating supply, which never goes down.