hookit-mcp 0.4.0 → 0.5.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), `HOOKIT_MEMORY_EVOLVE` / `HOOKIT_MEMORY_LENS` / `HOOKIT_MEMORY_FEE1` / `HOOKIT_MEMORY_FEE2` (override Memory on Evolve's pinned addresses).
+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), `HOOKIT_VELOCITY_FEE_PLUGIN` / `HOOKIT_VELOCITY_EVOLVE` / `HOOKIT_VELOCITY_EVOLVE_FEE1` / `HOOKIT_VELOCITY_EVOLVE_FEE2` (override Velocity Fee'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.
 
@@ -30,7 +30,7 @@ Coin names, tickers and descriptions are written by whoever launched the coin. T
 | `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`, `payout` and `evolve` (`{ feePct?, maxFeePct?, potPct? }`: this wallet becomes the coin's Evolve decider, below). `dryRun: true` checks and simulates without signing. |
+| `launch_token` | Launches in one call, with an optional `devBuyPct`, `payout`, `evolve` (`{ feePct?, maxFeePct?, potPct? }`: this wallet becomes the coin's Evolve decider, below) and `velocity` (`{ preset?, malusPct }`: Velocity Fee, 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. 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). |
@@ -52,6 +52,10 @@ Coin names, tickers and descriptions are written by whoever launched the coin. T
 | `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`. |
+| `velocity_set` | As the decider of an Evolve coin: `{ token, preset?, malusPct?, cashback?, cashbackPct?, sharePct?, slot?, dryRun? }` plugs Velocity (lowest free slot) with the 0 to 2 fee companions its malus needs in free slots above it, or re-plugs it with new settings; `unplug: true` unplugs Velocity and its companions together; `cancel: true` drops their announced changes. Refuses a wallet that is not the decider and a coin whose swap gas has no room; warns when the coin's fee cap leaves less room than the malus. `dryRun` is on unless `false`. |
+| `velocity_status` | Velocity on an Evolve coin, `{ token, sellAmount?, sellCoins? }`: each plug-in (slot, live or announced with its countdown, share, settings in words), its 4 h average against the price, the malus a sell would pay now, the companions and the plug-in each follows, the fee room and the cashback ledger. |
+| `velocity_cashback` | The Velocity cashback a wallet earned on an Evolve coin, `{ token, wallet? }`. |
+| `velocity_claim` | Claims this wallet's Velocity cashback, `{ token, to?, dryRun? }`, paid in the coin's quote. `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.
 
@@ -65,7 +69,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 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.
+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, ModuleRegistry, Velocity Fee and Velocity 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
 
@@ -133,6 +137,43 @@ memory_wallet({ "token": "0x…", "wallet": "0x…" })
 - 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.
 
+### Velocity on Evolve
+
+Velocity keeps a slow moving average of the coin's price (the mean: half-life 4 h, in the coin's own orientation). A sell whose price path runs below it, past a deadband, pays a malus on top of the coin's fee, growing with the depth up to the chosen malus and averaged over the sell's own path: a big dump pays more than a small sell, and splitting it saves almost nothing. A buy below the mean that brings the price back toward it earns cashback. Any decider can plug it (creator or agent), on new and existing Evolve coins.
+
+```
+velocity_set({ "token": "0x…", "preset": "balanced", "malusPct": 3, "dryRun": true })
+velocity_status({ "token": "0x…", "sellAmount": "0.5" })
+velocity_cashback({ "token": "0x…" })
+velocity_claim({ "token": "0x…", "dryRun": false })
+velocity_set({ "token": "0x…", "unplug": true, "dryRun": true })
+```
+
+- Presets (`halfLife` 4 h for all): `gentle` (deadband 1,500 ticks, about 14% below the mean), `balanced` (default, 1,000 ticks, about 10%), `strong` (500 ticks, about 5%). The malus is full 1,000 ticks beyond the deadband per 1% of malus (`balanced` at 3%: 3,000 ticks beyond the deadband, so the full malus from about 33% below the mean); `gentle` doubles that depth (at most 20,000 ticks), `strong` halves it (at least 100). A tick is 0.01%.
+- `malusPct` 0 to 3 (default 3). Evolve caps each hook's fee at 1%, so Velocity asks the 1st percent and up to two fee companions (VelocityEvolveFee rank 1 and 2) the 2nd and 3rd: none up to 1%, one up to 2%, two up to 3%, each fee-only (share 0, config `0x`) in a free slot above Velocity's. A companion follows the Velocity plug-in in a lower slot when it is plugged, so a re-plug re-plugs them too; `velocity_set` does all of it, one transaction each.
+- Cashback (on by default): `cashbackBps` 100% of the Evolve fee a dip buy paid (`cashbackPct` lowers it), times how well it closes the gap (most when it ends at the mean). It is paid from Velocity's share of Evolve's fees (`sharePct`, default 20%); on Evolve it is always on, because the catalog requires Velocity to take a share and a share pays cashback (`cashback: false` is refused). The 1% base fee is never given back. Each wallet claims its own (`velocity_claim`), also after an unplug.
+- Swap gas: Velocity takes 38,000 of the coin's 120,000 and each companion 41,000, so Velocity with both companions takes it all. `velocity_set` refuses when Memory (or another hook that runs in every swap) leaves too little, and says which malus still fits.
+- Fee room: Evolve adds the malus to its own fee and clamps the sum to the coin's fee cap. `velocity_set` warns when the cap minus Evolve's fee is below the malus (e.g. a 4% cap with a 3% fee leaves 1%); lower Evolve's fee with `evolve_decide` to leave it room.
+- A plug-in's settings never change: new settings re-plug Velocity in its slot after the notice, and its mean restarts at its first trade. Every plug-in, re-plug and unplug applies after the coin's notice.
+- Unplug with `velocity_set { unplug: true }`: it empties Velocity's slot and its companions' slots together (announces hook `0xFFFF`, none). A companion left alone keeps reading Velocity's last mean and asks a malus that fades out within a few half-lives.
+- Its `config` for `evolve_plug` is `abi.encode(Setup)`, `Setup = (uint32 halfLife, uint16 deadbandTicks, uint16 fullDepthTicks, uint16 malusBps, uint16 cashbackBps)`; its companions take `0x`. The catalog ids are found by scanning EvolveExtensions' list for the pinned addresses.
+- Live on Ink since hookit-mcp 0.5.0: VelocityEvolve `0xA76B2081A521AD03d773B7A4EB38088DAcaDA628`, its companions `0xebA39A6E554580f8F4c0aEB9B58Ead323D34eC95` (rank 1) and `0x90ffeF641eBAdea46Fb2Ae94e64e94aF7F9e2f7F` (rank 2). `HOOKIT_VELOCITY_EVOLVE`, `HOOKIT_VELOCITY_EVOLVE_FEE1` and `HOOKIT_VELOCITY_EVOLVE_FEE2` override them; nothing is used unless code is there and the contracts point at each other.
+
+## Velocity Fee at launch
+
+A coin without Evolve gets Velocity Fee at launch: `launch_token` with `velocity`.
+
+```
+launch_token({ "name": "Calm Kitty", "symbol": "CALM", "hookTaxPct": 5, "modules": { "autoBurn": true, "autoBurnPct": 90 }, "velocity": { "preset": "balanced", "malusPct": 3 }, "dryRun": true })
+```
+
+- The same curves as on Evolve (`preset`), and `malusPct` 1 to 9. The plugin is registered in ModuleRegistry once per malus tier (0%, 1%, … 9%): the malus counts as its tier, rounded up to a whole percent, and **1% base + hook tax + tier must stay at most 10%** (a 6% hook tax leaves a 3% malus; no hook tax leaves 9%). With dynamic fees the hook tax is the top of the range minus the base. The server finds the tier's module id by scanning the registry for the pinned plugin with that ceiling; ids are never hard-coded.
+- Rebates: only when buys pay a hook tax (a static hook tax above 0, or dynamic fees whose minimum total is above 1%). Then a buy below the mean gets back up to all of the hook tax on the part of the buy that closes the gap, paid from Velocity's 10% share of the hook pot, and the coin's other destinations take the other 90% (the pot routes still total 100%). Otherwise Velocity runs the malus alone, with no pot share, and the dry run says so. The 1% base fee is always paid.
+- Its malus goes into the hook pot and is split like the hook tax; the coin's pot needs destinations.
+- Refused with Evolve (plug Velocity on Evolve instead) and with NFT Strategy.
+- The launch is prepared by hookit.fun; before signing, the server decodes the transaction and checks it carries exactly Velocity's slot: the tier's module, the init data `abi.encode(Params)` with `Params = (uint32 halfLife, uint16 deadbandTicks, uint16 fullDepthTicks, uint16 maxSurchargeBps, uint16 rebateBps)` built from the preset and the launch's own fees, the pot share, and the 10% rule. Anything else is refused and nothing is sent.
+- Live on Ink since hookit-mcp 0.5.0: VelocityFeePlugin `0x99772E2199da48e0d1388A3776F96b4257A49E8E`, registered for the 0% to 9% tiers. `HOOKIT_VELOCITY_FEE_PLUGIN` overrides it.
+
 ## 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.