feat(defi): add evm_tx_handler PR1 (quote, preview, transfer)

[Hendobox]

Part of #142 (edited by rosspeili)

Summary

Adds defi/evm_tx_handler - a Skillware skill for a dedicated EVM agent wallet on Ethereum and Base, driven by structured JSON intent (no slash commands; no NLP inside skill.py).

PR1 (this PR):

Action	Purpose
resolve	Merge intent with config + YAML registries; missing_fields / suggested_defaults
quote / preview	Uniswap V2 quotes (getAmountsIn / getAmountsOut, slippage, gas estimate)
transfer	Native + ERC20 sends; addressbook labels; confirmed gate
balances / wallet_info / update_preferences	Read wallet state; persist whitelisted prefs
execute	Stubbed for PR2 (not_available); honors needs_confirmation when enabled

PR2 (follow-up): swap execute (approve + router), max_trade_usd, optional USD preview.

Boundaries

• Agent: natural language → partial intent, previews, user approval, confirmed: true
• Skill: validation, quotes, signing transfers, structured JSON only

Security / ops

• AGENT_WALLET_PRIVATE_KEY in .env only — never tool args or YAML
• config.yaml gitignored; example committed
• Replace data/addressbook.yaml placeholders before mainnet use
• Base DEGEN address verified on BaseScan

Dependencies

web3>=6.0.0, pyyaml (via manifest.yaml / SkillLoader).

Test plan

• pytest skills/defi/evm_tx_handler/test_skill.py tests/test_skill_issuer.py -q (mocked Web3, no live keys)
• SkillLoader.load_skill("defi/evm_tx_handler") with web3 installed
• Optional maintainer smoke: resolve → quote on Base with test RPC

Reviewer focus

• data/chains.yaml router / WETH addresses
• data/tokens.yaml (Base degen)
• Transfer + confirmation vs manifest.yaml constitution
• OK to merge without swap execute until PR2?

Follow-up

PR2: execute, receipt handling, max_trade_usd, optional CoinGecko USD in preview.

[rosspeili]

Thanks for the thorough work on this new skill @Hendobox, this is a strong first pr and clearly tracks #142.

The architecture matches what we asked for: structured intent only in the skill, agent handles NL, YAML registries, confirmation gates, and mocked Web3 tests. Security choices (gitignored config, fail-closed RPC, key redaction, placeholder addressbook) look thoughtful. Good call splitting swap execute into a second pr.

Before merge we could build the full MVP from #142 in place, so we plan to wait for pr2 rather than merge pr1 alone. The main gap is swap execute, quotes and transfers are useful, but the core buy/sell flow is not complete yet.

Small asks for this PR or the next commit:

• Link Part of [New Skill]: defi/evm_tx_handler — NLP-driven agent wallet for EVM buy/sell/send #142 (or Fixes [New Skill]: defi/evm_tx_handler — NLP-driven agent wallet for EVM buy/sell/send #142 when pr2 lands) in the PR description or I would make pr2 into a new commit here, and we can merge all commits, instead of squash and merge for auditability.
• Add CI coverage: install web3 and run pytest skills/defi/evm_tx_handler/test_skill.py
• Add a [Unreleased] CHANGELOG entry when we merge
• pr2/next commit: swap execute with approve + router, max_trade_usd enforcement, optional USD preview, and tests for execute

Tips for next wave: reuse the quote payload (path, min_out, deadline) in execute so quote and broadcast stay consistent; mock approve + swap in tests the same way you mocked transfer.

Happy to keep reviewing on the same branch or a stacked pr2, 100% up to you. Nice work on a fairly complex skill. Did you checked ARPAHLS/OPSIE's web3 handler or built this from scratch?

[Hendobox]

Thanks for the detailed review — agreed on waiting for the full MVP before merging.

Plan: I’ll stack PR2 on this same branch (feat/evm-tx-handler-pr1) as a separate commit (no squash), so you get PR1 + execute in one merge for auditability. I’ll update the description to Part of #142 now and switch to Fixes #142 once execute lands.

This commit / next push:

CI: install web3>=6.0.0 and run pytest skills/defi/evm_tx_handler/test_skill.py
[Unreleased] CHANGELOG entry for defi/evm_tx_handler
Next commit (PR2):

execute: approve + Uni V2 router swap, reusing the quote payload (path, min_out_wei, deadline) so quote and broadcast stay aligned
max_trade_usd enforcement (fail closed if price unavailable when cap is set)
Optional CoinGecko USD in preview
Mocked tests for approve + swap (same pattern as transfer)
OPSIE / built from scratch: I read the issue’s OPSIE web3_handler.py notes for feature ideas only (multi-chain, registries, preview/confirm, gas policy) - did not port code or slash-command flow. This is a clean Skillware implementation: action-based execute(), YAML registries, no NLP/input() in the skill, dedicated agent wallet only. Happy to cross-check specific OPSIE paths if you want parity on anything before PR2.

[rosspeili]

Thanks for the quick follow-up and for stacking next steps on the same branch, this will be smoother i think.

On the latest commit: please drop the CI changes for now (revert 0ff55fe or leave them out of the PR). We are going to refresh CI in the next release so it matches how the repo actually works today (packaging, skill deps, test layout). We do not want per-skill hardcoding in .github/workflows/ci.yml on each new skill PR.

Keep building PR2 on the same branch (execute, caps, USD preview, tests). We will review together the full series once swap execute is in. CHANGELOG can land with the final merge.

Appreciate the OPSIE note, yes it was nice to view but it is from 2022-23, so clean Skillware implementation is exactly what we wanted. <3

[rosspeili]

Thanks again @Hendobox, the new commit lands the full #142 MVP. CI revert was the right call, we’ll handle CI in #151. We’re ready to merge once the items below are in.

Please add on this branch (one final polish commit is fine):

1. Example script (required), Add a runnable example (e.g. examples/gemini_evm_tx_handler.py and/or Claude sibling) plus a row in examples/README.md. Follow the wallet_screening pattern: load bundle, resolve → quote → preview → execute flow with mocked or clearly documented env setup.

2. Catalog page, Expand docs/skills/evm_tx_handler.md with Gemini and Claude usage sections like other catalog pages (snippets + link to examples).

3. Agent-facing docs, In instructions.md (and briefly in the catalog page):

   • execute re-quotes on chain at broadcast time, preview amounts may drift, agent should quote immediately before confirm/execute.
   • ERC20 swaps may require approve then swap, explain two-step flow and HITL when confirm_before_send is on.

4. Pre-flight checks, Before swap/transfer broadcast, check balance (and surface clear status/agent_hint when insufficient). Keep approve behavior, message it clearly for agents/users.

5. Private key UX, When AGENT_WALLET_PRIVATE_KEY (or configured private_key_env) is missing, return structured, agent-friendly guidance (disposable agent wallet only, set in .env, never personal/treasury keys, link to docs or something like this), not a bare exception string. Mirror the same wording in the catalog Environment section.

6. CHANGELOG, Single [Unreleased] entry with pinpoints if you want for each commit, when the above is done (full skill: quote/preview/execute/transfer, caps, USD preview). One entry for the whole PR series is fine, or check previous changelogs (still WIP, so take your approach).

7. Issuer email, Use your real contact email in manifest.yaml and card.json (not GitHub noreply), this will show users or people interested in the skill how to contact you if they need your expertise.

You do not need to change pyproject.toml, manifest requirements is enough, we’ll handle PyPI packaging/version and the website on our side after merge.

Optional, not blocking: manifest.name as defi/evm_tx_handler for tool/registry alignment (short evm_tx_handler is OK, this is under debate in relevant issues for all skills, but take a peek into other skills manifests to see how they approach it).

After that we’ll merge (merge commit, not squash), cut the release manually, and update the site. Solid work on a high-risk skill done cleanly. <3

[Hendobox]

Thanks for the detailed review and for confirming this lands the full #142 MVP. I’ll add the updates and keep everything on this branch so you can merge the full series with a merge commit.