wayfinder-paths 0.1.23__py3-none-any.whl → 0.1.24__py3-none-any.whl

wayfinder_paths/mcp/tools/execute.py

@@ -0,0 +1,770 @@
+from __future__ import annotations
+
+import os
+import re
+from typing import Any, Literal
+
+from eth_account import Account
+from eth_utils import to_checksum_address
+from pydantic import BaseModel, Field, ValidationError, model_validator
+from web3 import Web3
+
+from wayfinder_paths.core.clients.BRAPClient import BRAPClient
+from wayfinder_paths.core.clients.TokenClient import TokenClient
+from wayfinder_paths.core.constants import ZERO_ADDRESS
+from wayfinder_paths.core.constants.chains import CHAIN_CODE_TO_ID
+from wayfinder_paths.core.constants.contracts import TOKENS_REQUIRING_APPROVAL_RESET
+from wayfinder_paths.core.constants.erc20_abi import ERC20_ABI
+from wayfinder_paths.core.constants.hyperliquid import (
+    ARBITRUM_USDC_ADDRESS,
+    ARBITRUM_USDC_TOKEN_ID,
+    HYPERLIQUID_BRIDGE_ADDRESS,
+)
+from wayfinder_paths.core.utils.tokens import (
+    build_approve_transaction,
+    get_token_allowance,
+)
+from wayfinder_paths.core.utils.transaction import send_transaction
+from wayfinder_paths.mcp.preview import build_execution_preview
+from wayfinder_paths.mcp.state.profile_store import WalletProfileStore
+from wayfinder_paths.mcp.state.store import IdempotencyStore
+from wayfinder_paths.mcp.utils import (
+    err,
+    find_wallet_by_label,
+    normalize_address,
+    ok,
+    parse_amount_to_raw,
+    sha256_json,
+)
+
+
+class ExecutionRequest(BaseModel):
+    kind: Literal["swap", "send", "hyperliquid_deposit"]
+    wallet_label: str = Field(..., description="wallets.json label (e.g. main)")
+
+    # Shared
+    amount: str = Field(..., description="Human units as a string (e.g. '1000')")
+    recipient: str | None = Field(
+        default=None, description="Destination address (defaults to sender for swap)"
+    )
+
+    # swap-only
+    from_token: str | None = Field(default=None, description="Token id/address query")
+    to_token: str | None = Field(default=None, description="Token id/address query")
+    slippage_bps: int = Field(default=50, description="Slippage in bps (50 = 0.50%)")
+    deadline_seconds: int = Field(
+        default=300, description="Best-effort TTL for quoting"
+    )
+
+    # send-only
+    token: str | None = Field(
+        default=None, description="Token id/address query, or 'native'"
+    )
+    chain_id: int | None = Field(
+        default=None, description="Required when token='native'"
+    )
+
+    @model_validator(mode="after")
+    def _validate_kind(self) -> ExecutionRequest:
+        if not self.wallet_label.strip():
+            raise ValueError("wallet_label is required")
+        if self.kind == "swap":
+            if not (self.from_token and self.to_token):
+                raise ValueError("swap requires from_token and to_token")
+            if self.slippage_bps < 0:
+                raise ValueError("slippage_bps must be >= 0")
+            if self.deadline_seconds <= 0:
+                raise ValueError("deadline_seconds must be positive")
+        if self.kind == "send":
+            if not self.token:
+                raise ValueError("send requires token")
+            if not self.recipient:
+                raise ValueError("send requires recipient")
+            if str(self.token).strip().lower() == "native" and self.chain_id is None:
+                raise ValueError("send requires chain_id when token='native'")
+        if self.kind == "hyperliquid_deposit":
+            # Hard-coded Bridge2 deposit: Arbitrum USDC -> Hyperliquid bridge address.
+            # Allow callers to omit token/recipient entirely; if provided, they must match.
+            if self.recipient and _addr_lower(self.recipient) != _addr_lower(
+                HYPERLIQUID_BRIDGE_ADDRESS
+            ):
+                raise ValueError("hyperliquid_deposit recipient must be bridge address")
+            if self.token and str(self.token).strip() != ARBITRUM_USDC_TOKEN_ID:
+                raise ValueError(
+                    f"hyperliquid_deposit token must be {ARBITRUM_USDC_TOKEN_ID}"
+                )
+            if self.chain_id is not None and int(self.chain_id) != 42161:
+                raise ValueError(
+                    "hyperliquid_deposit chain_id must be 42161 (Arbitrum)"
+                )
+            try:
+                amt = float(self.amount)
+            except (TypeError, ValueError):
+                amt = None
+            if amt is not None and amt < 5:
+                raise ValueError(
+                    "hyperliquid_deposit amount must be >= 5 USDC (deposits below are lost)"
+                )
+        return self
+
+
+def _slippage_float(bps: int) -> float:
+    return max(0.0, float(int(bps)) / 10_000.0)
+
+
+def _addr_lower(addr: str | None) -> str | None:
+    if not addr:
+        return None
+    a = str(addr).strip()
+    return a.lower() if a else None
+
+
+def _chain_id_from_token(meta: dict[str, Any]) -> int | None:
+    # Token payloads often include an internal/db `id` field. Only accept:
+    # - meta["chain_id"] (preferred)
+    # - meta["chain"]["chain_id"] / ["chainId"] / ["id"]
+    if meta.get("chain_id") is not None:
+        try:
+            return int(meta.get("chain_id"))
+        except (TypeError, ValueError):
+            return None
+
+    chain = meta.get("chain") or {}
+    if not isinstance(chain, dict):
+        return None
+
+    for key in ("chain_id", "chainId", "id"):
+        if chain.get(key) is None:
+            continue
+        try:
+            return int(chain.get(key))
+        except (TypeError, ValueError):
+            return None
+
+    return None
+
+
+_SIMPLE_CHAIN_SUFFIX_RE = re.compile(r"^[a-z0-9]+\s+[a-z0-9-]+$", re.IGNORECASE)
+_ASSET_CHAIN_SPLIT_RE = re.compile(
+    r"^(?P<asset>[a-z0-9]+)[- _](?P<chain>[a-z0-9-]+)$", re.IGNORECASE
+)
+
+
+def _normalize_token_query(query: str) -> str:
+    q = " ".join(str(query).strip().split())
+    if not q or "-" in q or "_" in q:
+        return q
+    if not _SIMPLE_CHAIN_SUFFIX_RE.match(q):
+        return q
+    asset, chain_code = q.rsplit(" ", 1)
+    if chain_code.lower() in CHAIN_CODE_TO_ID:
+        return f"{asset}-{chain_code}"
+    return q
+
+
+def _is_eth_like_token(meta: dict[str, Any]) -> bool:
+    asset_id = str(meta.get("asset_id") or "").lower()
+    symbol = str(meta.get("symbol") or "").lower()
+    return asset_id == "ethereum" or symbol == "eth"
+
+
+def _split_asset_chain(query: str) -> tuple[str, str] | None:
+    q = str(query).strip()
+    if not q:
+        return None
+    m = _ASSET_CHAIN_SPLIT_RE.match(q)
+    if not m:
+        return None
+    return m.group("asset").lower(), m.group("chain").lower()
+
+
+async def _resolve_token_meta(
+    token_client: TokenClient,
+    *,
+    query: str,
+) -> tuple[str, dict[str, Any]]:
+    q = _normalize_token_query(query)
+    split = _split_asset_chain(q)
+    if split:
+        asset, chain_code = split
+        if asset in {"eth", "ethereum"}:
+            try:
+                gas_meta = await token_client.get_gas_token(chain_code)
+                if isinstance(gas_meta, dict) and _is_eth_like_token(gas_meta):
+                    return q, gas_meta
+            except Exception:
+                pass
+    meta = await token_client.get_token_details(q)
+    return q, meta
+
+
+def _infer_chain_code_from_query(query: str, meta: dict[str, Any]) -> str | None:
+    q = str(query).strip().lower()
+    if not q:
+        return None
+
+    candidates: set[str] = {str(k).lower() for k in CHAIN_CODE_TO_ID.keys()}
+    addrs = meta.get("addresses") or {}
+    if isinstance(addrs, dict):
+        candidates.update(str(k).lower() for k in addrs.keys())
+
+    best: str | None = None
+    for code in candidates:
+        if q.endswith(f"-{code}"):
+            if best is None or len(code) > len(best):
+                best = code
+    return best
+
+
+def _address_for_chain(meta: dict[str, Any], chain_code: str) -> str | None:
+    addrs = meta.get("addresses") or {}
+    if not isinstance(addrs, dict):
+        return None
+    for key, val in addrs.items():
+        if str(key).lower() == chain_code and val:
+            return str(val)
+    return None
+
+
+def _select_token_chain(
+    meta: dict[str, Any], *, query: str
+) -> tuple[int | None, str | None]:
+    chain_id = _chain_id_from_token(meta)
+    token_address = meta.get("address")
+
+    desired_chain = _infer_chain_code_from_query(query, meta)
+    if desired_chain:
+        addr = _address_for_chain(meta, desired_chain)
+        if addr:
+            token_address = addr
+        if desired_chain in CHAIN_CODE_TO_ID:
+            chain_id = CHAIN_CODE_TO_ID[desired_chain]
+
+    token_address_out = str(token_address).strip() if token_address else None
+    return chain_id, token_address_out
+
+
+def _sanitize_for_json(obj: Any) -> Any:
+    """Recursively convert HexBytes and bytes to hex strings for JSON serialization."""
+    if hasattr(obj, "hex") and callable(obj.hex):
+        return obj.hex()
+    if isinstance(obj, bytes):
+        return obj.hex()
+    if isinstance(obj, dict):
+        return {k: _sanitize_for_json(v) for k, v in obj.items()}
+    if isinstance(obj, (list, tuple)):
+        return [_sanitize_for_json(v) for v in obj]
+    return obj
+
+
+def _is_dry_run() -> bool:
+    return os.getenv("DRY_RUN", "").lower() in ("1", "true")
+
+
+def _make_sign_callback(private_key: str):
+    account = Account.from_key(private_key)
+
+    async def sign_callback(transaction: dict) -> bytes:
+        signed = account.sign_transaction(transaction)
+        return signed.raw_transaction
+
+    return sign_callback
+
+
+async def _broadcast(
+    sign_callback,
+    tx: dict[str, Any],
+    *,
+    chain_id: int,
+) -> tuple[bool, dict[str, Any]]:
+    if _is_dry_run():
+        return True, {"dry_run": True, "transaction": tx, "chain_id": chain_id}
+    try:
+        tx_hash = await send_transaction(tx, sign_callback, wait_for_receipt=True)
+        return True, {"tx_hash": tx_hash, "chain_id": chain_id}
+    except Exception as e:
+        return False, {"error": _sanitize_for_json(str(e)), "chain_id": chain_id}
+
+
+async def _ensure_allowance(
+    *,
+    sign_callback,
+    chain_id: int,
+    token_address: str,
+    owner: str,
+    spender: str,
+    amount: int,
+) -> tuple[bool, list[dict[str, Any]]]:
+    # May emit 0-allowance clear tx for tokens requiring approval reset (e.g. USDT)
+    effects: list[dict[str, Any]] = []
+
+    allowance = await get_token_allowance(
+        token_address=token_address,
+        chain_id=chain_id,
+        owner_address=owner,
+        spender_address=spender,
+    )
+
+    token_checksum = to_checksum_address(token_address)
+    if (chain_id, token_checksum) in TOKENS_REQUIRING_APPROVAL_RESET and allowance > 0:
+        clear_tx = await build_approve_transaction(
+            from_address=owner,
+            chain_id=chain_id,
+            token_address=token_checksum,
+            spender_address=spender,
+            amount=0,
+        )
+        sent_ok, sent = await _broadcast(sign_callback, clear_tx, chain_id=chain_id)
+        effects.append({"type": "tx", "label": "approve_clear", **sent})
+        if not sent_ok:
+            return False, effects
+        # After clear, we will still submit a fresh approve below.
+
+    if allowance >= int(amount):
+        return True, effects
+
+    approve_tx = await build_approve_transaction(
+        from_address=owner,
+        chain_id=chain_id,
+        token_address=token_checksum,
+        spender_address=spender,
+        amount=int(amount),
+    )
+
+    sent_ok, sent = await _broadcast(sign_callback, approve_tx, chain_id=chain_id)
+    effects.append({"type": "tx", "label": "approve", **sent})
+    return sent_ok, effects
+
+
+def _annotate_profile(
+    *,
+    address: str,
+    label: str,
+    protocol: str,
+    action: str,
+    status: str,
+    chain_id: int | None = None,
+    details: dict[str, Any] | None = None,
+    idempotency_key: str | None = None,
+) -> None:
+    store = WalletProfileStore.default()
+    store.annotate_safe(
+        address=address,
+        label=label,
+        protocol=protocol,
+        action=action,
+        tool="execute",
+        status=status,
+        chain_id=chain_id,
+        details=details,
+        idempotency_key=idempotency_key,
+    )
+
+
+async def execute(
+    *,
+    request: dict[str, Any],
+    idempotency_key: str | None = None,
+    force: bool = False,
+) -> dict[str, Any]:
+    if isinstance(request, dict) and "kind" not in request and "action" in request:
+        # Back-compat: some callers use "action":"swap|send".
+        request = {**request, "kind": request.get("action")}
+    try:
+        req = ExecutionRequest.model_validate(request)
+    except ValidationError as exc:
+        return err("invalid_request", "execute.request validation failed", exc.errors())
+
+    store = IdempotencyStore.default()
+
+    tool_input = {
+        "request": req.model_dump(mode="json"),
+        "idempotency_key": idempotency_key,
+    }
+    preview_obj = build_execution_preview(tool_input)
+    preview_text = str(preview_obj.get("summary") or "").strip()
+
+    key = (idempotency_key or "").strip() or sha256_json(tool_input.get("request"))
+    prior = store.get(key)
+    if prior and not force:
+        # Ignore cached preflight errors (no side effects) so fixes/config changes can be retried.
+        if isinstance(prior, dict) and prior.get("ok") is False:
+            prior = None
+        else:
+            # Return the previous response, but annotate status for clarity.
+            try:
+                prior_result = prior.get("result") if isinstance(prior, dict) else None
+                if isinstance(prior_result, dict):
+                    prior_result["status"] = "duplicate"
+                    prior_result["idempotency_key"] = key
+                    prior_result.setdefault("preview", preview_text)
+            except Exception:
+                pass
+            return prior
+
+    w = find_wallet_by_label(req.wallet_label)
+    if not w:
+        response = err("not_found", f"Unknown wallet_label: {req.wallet_label}")
+        store.put(key, tool_input, response)
+        return response
+
+    sender = normalize_address(w.get("address"))
+    pk = (
+        (w.get("private_key") or w.get("private_key_hex"))
+        if isinstance(w, dict)
+        else None
+    )
+    if not sender or not pk:
+        response = err(
+            "invalid_wallet",
+            "Wallet must include address and private_key_hex in wallets.json (local dev only)",
+            {"wallet_label": req.wallet_label},
+        )
+        store.put(key, tool_input, response)
+        return response
+
+    sign_callback = _make_sign_callback(pk)
+
+    effects: list[dict[str, Any]] = []
+
+    if req.kind == "swap":
+        rcpt = normalize_address(req.recipient) or sender
+        token_client = TokenClient()
+        brap_client = BRAPClient()
+        try:
+            from_q, from_meta = await _resolve_token_meta(
+                token_client, query=str(req.from_token)
+            )
+            to_q, to_meta = await _resolve_token_meta(
+                token_client, query=str(req.to_token)
+            )
+        except Exception as exc:  # noqa: BLE001
+            response = err("token_error", str(exc))
+            store.put(key, tool_input, response)
+            return response
+
+        from_chain_id, from_token_addr = _select_token_chain(from_meta, query=from_q)
+        to_chain_id, to_token_addr = _select_token_chain(to_meta, query=to_q)
+        if from_chain_id is None or to_chain_id is None:
+            response = err(
+                "invalid_token",
+                "Could not resolve chain_id for one or more tokens",
+                {"from_chain_id": from_chain_id, "to_chain_id": to_chain_id},
+            )
+            store.put(key, tool_input, response)
+            return response
+        if not from_token_addr or not to_token_addr:
+            response = err(
+                "invalid_token",
+                "Could not resolve token address for one or more tokens",
+                {
+                    "from_token_address": from_token_addr,
+                    "to_token_address": to_token_addr,
+                },
+            )
+            store.put(key, tool_input, response)
+            return response
+
+        decimals = int(from_meta.get("decimals") or 18)
+        try:
+            amount_raw = parse_amount_to_raw(req.amount, decimals)
+        except ValueError as exc:
+            response = err("invalid_amount", str(exc))
+            store.put(key, tool_input, response)
+            return response
+
+        try:
+            quote_data = await brap_client.get_quote(
+                from_token=from_token_addr,
+                to_token=to_token_addr,
+                from_chain=from_chain_id,
+                to_chain=to_chain_id,
+                from_wallet=sender,
+                from_amount=str(amount_raw),
+            )
+        except Exception as exc:  # noqa: BLE001
+            response = err("quote_error", str(exc))
+            store.put(key, tool_input, response)
+            return response
+
+        best_quote = (
+            quote_data.get("best_quote") if isinstance(quote_data, dict) else None
+        )
+        if not isinstance(best_quote, dict):
+            response = err(
+                "quote_error", "No best_quote returned", {"quote": quote_data}
+            )
+            store.put(key, tool_input, response)
+            return response
+
+        calldata = best_quote.get("calldata") or {}
+        if not isinstance(calldata, dict) or not calldata:
+            response = err(
+                "quote_error", "best_quote missing calldata", {"best_quote": best_quote}
+            )
+            store.put(key, tool_input, response)
+            return response
+
+        swap_tx = dict(calldata)
+        swap_tx["chainId"] = int(from_chain_id)
+        swap_tx["from"] = to_checksum_address(sender)
+
+        token_addr = from_token_addr
+        spender = swap_tx.get("to")
+        approve_amount = (
+            best_quote.get("input_amount")
+            or best_quote.get("inputAmount")
+            or best_quote.get("amount1")
+            or best_quote.get("amount")
+        )
+
+        if (
+            token_addr
+            and isinstance(token_addr, str)
+            and token_addr.strip()
+            and token_addr.lower() != ZERO_ADDRESS.lower()
+            and spender
+            and approve_amount is not None
+        ):
+            try:
+                need = int(approve_amount)
+            except Exception:
+                need = int(amount_raw)
+            ok_allow, approval_effects = await _ensure_allowance(
+                sign_callback=sign_callback,
+                chain_id=int(from_chain_id),
+                token_address=token_addr,
+                owner=to_checksum_address(sender),
+                spender=to_checksum_address(str(spender)),
+                amount=need,
+            )
+            effects.extend(approval_effects)
+            if not ok_allow:
+                response = ok(
+                    {
+                        "idempotency_key": key,
+                        "status": "failed",
+                        "dry_run": _is_dry_run(),
+                        "kind": "swap",
+                        "sender": sender,
+                        "recipient": rcpt,
+                        "preview": preview_text,
+                        "effects": effects,
+                        "raw": {"quote": quote_data},
+                    }
+                )
+                store.put(key, tool_input, response)
+                return response
+
+        sent_ok, sent = await _broadcast(
+            sign_callback, swap_tx, chain_id=int(from_chain_id)
+        )
+        effects.append({"type": "tx", "label": "swap", **sent})
+
+        status = (
+            "confirmed"
+            if (sent_ok and not _is_dry_run())
+            else ("dry_run" if sent_ok else "failed")
+        )
+        response = ok(
+            {
+                "idempotency_key": key,
+                "status": status,
+                "dry_run": _is_dry_run(),
+                "kind": "swap",
+                "sender": sender,
+                "recipient": rcpt,
+                "preview": preview_text,
+                "effects": effects,
+                "raw": {"quote": quote_data, "best_quote": best_quote},
+            }
+        )
+        store.put(key, tool_input, response)
+
+        _annotate_profile(
+            address=sender,
+            label=req.wallet_label,
+            protocol="brap",
+            action="swap",
+            status=status,
+            chain_id=int(from_chain_id),
+            details={
+                "from_token": str(req.from_token),
+                "to_token": str(req.to_token),
+                "amount": req.amount,
+            },
+            idempotency_key=key,
+        )
+
+        return response
+
+    is_hl_deposit = req.kind == "hyperliquid_deposit"
+    recipient = (
+        normalize_address(HYPERLIQUID_BRIDGE_ADDRESS)
+        if is_hl_deposit
+        else normalize_address(req.recipient)
+    )
+    if not recipient:
+        response = err("invalid_request", "recipient is required for send")
+        store.put(key, tool_input, response)
+        return response
+
+    token_q = ARBITRUM_USDC_TOKEN_ID if is_hl_deposit else str(req.token or "").strip()
+    token_client = TokenClient()
+
+    if token_q.lower() == "native":
+        chain_id = int(req.chain_id or 0)
+        if chain_id <= 0:
+            response = err(
+                "invalid_request", "chain_id must be provided for native sends"
+            )
+            store.put(key, tool_input, response)
+            return response
+        # Native send uses 18 decimals.
+        try:
+            value = parse_amount_to_raw(req.amount, 18)
+        except ValueError as exc:
+            response = err("invalid_amount", str(exc))
+            store.put(key, tool_input, response)
+            return response
+
+        tx = {
+            "chainId": chain_id,
+            "from": to_checksum_address(sender),
+            "to": to_checksum_address(recipient),
+            "value": int(value),
+        }
+        sent_ok, sent = await _broadcast(sign_callback, tx, chain_id=chain_id)
+        effects.append({"type": "tx", "label": "send_native", **sent})
+        status = (
+            "confirmed"
+            if (sent_ok and not _is_dry_run())
+            else ("dry_run" if sent_ok else "failed")
+        )
+        response = ok(
+            {
+                "idempotency_key": key,
+                "status": status,
+                "dry_run": _is_dry_run(),
+                "kind": req.kind,
+                "sender": sender,
+                "recipient": recipient,
+                "preview": preview_text,
+                "effects": effects,
+                "raw": {"transaction": tx},
+            }
+        )
+        store.put(key, tool_input, response)
+        _annotate_profile(
+            address=sender,
+            label=req.wallet_label,
+            protocol="balance",
+            action="send_native",
+            status=status,
+            chain_id=chain_id,
+            details={"recipient": recipient, "amount": req.amount},
+            idempotency_key=key,
+        )
+
+        return response
+
+    try:
+        token_meta = await token_client.get_token_details(token_q)
+    except Exception as exc:  # noqa: BLE001
+        response = err("token_error", str(exc))
+        store.put(key, tool_input, response)
+        return response
+
+    token_address = str(token_meta.get("address") or "").strip()
+    chain_id = _chain_id_from_token(token_meta)
+    if not token_address or chain_id is None:
+        response = err(
+            "invalid_token", "Token missing address/chain_id", {"token": token_meta}
+        )
+        store.put(key, tool_input, response)
+        return response
+    if is_hl_deposit:
+        if int(chain_id) != 42161:
+            response = err(
+                "invalid_token",
+                "Hyperliquid deposits require Arbitrum USDC (chain_id 42161)",
+                {"token": token_meta, "chain_id": chain_id},
+            )
+            store.put(key, tool_input, response)
+            return response
+        if _addr_lower(token_address) != _addr_lower(ARBITRUM_USDC_ADDRESS):
+            response = err(
+                "invalid_token",
+                "Resolved USDC token address does not match expected Arbitrum USDC",
+                {"token": token_meta, "expected": ARBITRUM_USDC_ADDRESS},
+            )
+            store.put(key, tool_input, response)
+            return response
+
+    decimals = int(token_meta.get("decimals") or 18)
+    try:
+        amount_raw = parse_amount_to_raw(req.amount, decimals)
+    except ValueError as exc:
+        response = err("invalid_amount", str(exc))
+        store.put(key, tool_input, response)
+        return response
+
+    w3 = Web3()
+    contract = w3.eth.contract(
+        address=to_checksum_address(token_address), abi=ERC20_ABI
+    )
+    data = contract.encode_abi(
+        "transfer", args=[to_checksum_address(recipient), int(amount_raw)]
+    )
+    tx = {
+        "chainId": int(chain_id),
+        "from": to_checksum_address(sender),
+        "to": to_checksum_address(token_address),
+        "data": data,
+        "value": 0,
+    }
+
+    sent_ok, sent = await _broadcast(sign_callback, tx, chain_id=int(chain_id))
+    effects.append(
+        {
+            "type": "tx",
+            "label": "hyperliquid_deposit" if is_hl_deposit else "send_erc20",
+            **sent,
+        }
+    )
+
+    status = (
+        "confirmed"
+        if (sent_ok and not _is_dry_run())
+        else ("dry_run" if sent_ok else "failed")
+    )
+    response = ok(
+        {
+            "idempotency_key": key,
+            "status": status,
+            "dry_run": _is_dry_run(),
+            "kind": req.kind,
+            "sender": sender,
+            "recipient": recipient,
+            "preview": preview_text,
+            "effects": effects,
+            "raw": {"token": token_meta, "transaction": tx},
+        }
+    )
+    store.put(key, tool_input, response)
+    _annotate_profile(
+        address=sender,
+        label=req.wallet_label,
+        protocol="hyperliquid" if is_hl_deposit else "balance",
+        action="hyperliquid_deposit" if is_hl_deposit else "send_erc20",
+        status=status,
+        chain_id=int(chain_id),
+        details={
+            "recipient": recipient,
+            "amount": req.amount,
+            "token": token_q,
+        },
+        idempotency_key=key,
+    )
+
+    return response