Add swap action via PuddleSwap (Monad testnet)

[manisaigaddam]

What this changes

Adds a testnet swap action so the agent can trade tokens on Monad, not only send them.

Router: PuddleSwap — portdeveloper's Uniswap V2 DEX on Monad testnet (chainId 10143). Quotes are batched eth_calls to the router (getAmountsOut via Multicall3). No swap API and no extra key.

I looked at Monorail Pathfinder first (mentioned in the claim). The testnet Pathfinder endpoint was not usable from here, so this PR pins one RPC-only DEX instead of shipping a dead aggregator client. PancakeSwap / Uniswap V3 / other venues are a follow-up: they are not Uniswap V2 getAmountsOut routers.

Closes #14

Behaviour

• New action: {"action":"swap","amountIn":"0.1","tokenIn":"MON","tokenOut":"USDC"}
• Slash command: /swap 0.1 MON USDC (skips the model)
• Natural language: "swap 0.1 MON for USDC" via JSON from QVAC, with a phrase fallback for small models
• Candidate paths match PuddleSwap's star routing: direct pair, then 1-hop and 2-hop through USDC / USDT / WMON. Best getAmountsOut wins; confirm is y/N like send
• At y, one silent re-quote (Uniswap/CowSwap "fresh quote before sign"). If output is still ≥ the min-out that was shown, that path is locked. If it fell below, refuse (cancel and /swap again). If RPC fails, keep the snapshot. No 6s ticker, no second prompt
• Deadline is 10 minutes after confirm (router timestamp is set at lock, not while the preview sits)
• Native MON in/out is supported. MON ↔ WMON is a wrap, not a swap, and is refused
• ERC-20 approve is an exact amount, batched with the swap into one UserOp
• Default slippage 1% (PuddleSwap's default; SWAP_SLIPPAGE_PERCENT). Mainnet has dex: null and refuses
• Output goes to the agent's own Safe (no address-book recipient)
• Spend policy (Declarative spend policy: per-send and per-session limits plus an address allowlist #50): native MON in hits maxPerSend / maxPerSession and charges the session. ERC-20-in + those MON limits → refuse (cannot be evaluated). Allowlist does not apply

Pinned testnet addresses (from portdeveloper/puddleswap config/addresses/10143.json):

• Router: 0x430c23895c8D44883526e3E0B09327dAD8766660
• Puddle WMON (pools): 0x97B3070F9Da6C002343862b35E68Bd8e22608943
• USDC: 0x534b2f3A21130d7a60830c2Df862319e593943A3
• USDT: 0x1314b22df27BDcD4F8D11a0f4185943e55748917

Official catalog WMON 0xFb8b…c541 is still used for balance reads. Swap routing uses Puddle's wrap, because that is where the pools live.

How I tested it

• npm run build succeeds
• Swap + policy unit tests pass (test/swap.test.mjs, test/policy.test.mjs)
• Full npm test on Windows: pre-existing test/fetch-model.test.mjs failures (C:\tmp missing). CI is Ubuntu; that test is unrelated to swap
• npm run smoke: swap section passed (live quote + dry-run UserOp). Full SMOKE_OK can still fail on the existing NL send path when SmolLM2 truncates an address — not introduced by this PR
• Live router quote + dry-run swap
• Confirmed testnet broadcast (native MON gas, same Safe UserOp path): 0x13e3caad…

Model / platform: Windows, Node 22, local SmolLM2 GGUF, MONAD_NETWORK=testnet.

Live quote (0.1 MON → USDC)

Best path is still MON → USDT → USDC (~2.11 USDC) vs direct MON → USDC (~0.41 USDC). Thin testnet pools, not agent arbitrage. Confirm shows that one winning route.

parseAction("swap 0.1 MON for USDC") → {"action":"swap","amountIn":"0.1","tokenIn":"MON","tokenOut":"USDC"}

Scope check

• This stays within v0 scope (native MON, single account, testnet), OR
• This grows v0: testnet token swaps via PuddleSwap (swap + /swap). Mainnet still refuses. No bridges, no mainnet DEX, no second aggregator in this PR.

Issue #14 pointed at src/tools.mjs and src/wallet.mjs. Those two are where the action is registered and the UserOp is sent. The extra files are the minimum to keep DEX math out of the wallet layer, wire /swap, pin the testnet router, and stop existing tests from treating swap as unknown.

Conventions

• I used npm (not pnpm/yarn) and did not add a global sodium-native override.
• I did not commit .env, seeds, keys, or model weights.
• One change: the swap action. One PR.

[portdeveloper]

Please rebase onto current main now that #50 has landed and define the spend-policy behavior for swaps. The current branch bypasses policy completely, so a native MON swap does not hit maxPerSend or maxPerSession, and session accounting never advances. A configured policy must not silently allow a write it cannot evaluate; enforce the applicable rules or refuse the swap with a clear reason, with focused tests.

The core transaction builder is not covered by the new unit suite. test/swap.test.mjs checks parsing and route helpers, but it never decodes buildSwapCalls(). Add calldata tests for the native-input, native-output, and token-to-token branches, including the approval call, and verify the router target, call value, path, recipient, deadline, and min-out.

The advertised dry-run does not currently prove those calls execute. sendCalls() catches every quoteSendTransaction() failure and still returns a successful DRY RUN, so bad calldata, a router revert, and an unavailable estimator are indistinguishable. Fail closed when an available simulation rejects the calls, or provide a confirmed testnet broadcast that exercises the built UserOp before merge.

One smaller confirmation bug also contradicts the documented behavior: Number.parseInt() accepts input such as 1junk as route 1 even though anything except y or a listed number should cancel. Require the entire trimmed answer to be a valid route number and test it.

[manisaigaddam]

Rebased onto current main (#50) and addressed the review.

Spend policy. Swaps no longer bypass it. Native MON in hits maxPerSend / maxPerSession before confirm; a successful (including dry-run) native swap charges the session budget. ERC-20-in + those MON limits → refuse (cannot be evaluated), not a silent skip. Allowlist stays a send-recipient rule (swap output returns to the agent's Safe). Focused tests in test/policy.test.mjs.

buildSwapCalls(). Unit tests now decode native-in, native-out, and token-to-token calldata (approve when needed): router, value, path, recipient, deadline, min-out.

Dry-run. sendCalls() fails closed on a revert-like estimator rejection. Unavailable bundler is still a dry-run (CI without a key). Plus a confirmed testnet broadcast:

• 0.1 MON → USDC, native gas (WDK_GAS_MODE=native)
• Route signed: MON → USDT → USDC (~2.112923 USDC; direct pool was ~0.405443)
• Tx: https://testnet.monadscan.com/tx/0x13e3caadca8cc2d0e394e85a7c1b5bde84339dd120f4ce31b69a9c84f938a609
• Safe 0x4aED2D262fc784D1A81dDa448d95a035d0D3a65B — MON 10.0 → 9.59082886575, USDC 0 → 2.112923

Confirm parser. Whole-string match only (y / 1–n). 1junk cancels. Tested.

npm run build ok. Swap/policy/related unit tests 110 pass.

[manisaigaddam]

Follow-up on the same PR (0888f64) — confirm flow now matches PuddleSwap / Uniswap more closely. Description above is updated; this is the delta since the last review reply.

Auto-best + y/N. Every star path is still quoted. Only the winning path is shown. Confirm is the same y/N as send (no 1/2/3). 1junk cannot pick a route because there is no route number parser left.

Re-quote at confirm, then freeze. At y we re-quote once (no ticker, no second prompt). If fresh output is still ≥ the min-out that was shown, we lock (and raise the floor if the quote got better). If it dropped below, refuse — cancel and /swap again. If RPC fails, keep the snapshot. Execution then uses that frozen path + min-out.

Multicall3. Quotes go through 0xcA11bde0… aggregate3 (allowFailure: true), same pattern as the PuddleSwap app. Parallel eth_calls if Multicall3 is unreachable.

Defaults. Slippage 1% (PuddleSwap). Deadline still 10 minutes, clock starts at confirm — preview now says 10 minutes after confirm.

Policy reuse (no new policy.json keys). Native MON in still hits maxPerSend / maxPerSession. The dummy 0x…0001 recipient is gone; sends and native-in swaps share the same amount-limit helper. ERC-20-in + those MON limits still refuses (cannot be evaluated) — that is the review rule, not a skip.

No new broadcast. The native-gas UserOp from the last comment still stands: https://testnet.monadscan.com/tx/0x13e3caadca8cc2d0e394e85a7c1b5bde84339dd120f4ce31b69a9c84f938a609

Swap + policy unit tests pass. Windows npm test can still fail on pre-existing fetch-model /tmp writes; unrelated to swap.

[portdeveloper]

The substantive swap blockers from the previous review are resolved: spend policy is enforced, calldata is decoded in tests, route selection is strict, the quote is refreshed without weakening the displayed min-out, and the linked successful UserOp contains the expected PuddleSwap swap call.

Before approval, please rebase onto current main now that #55 has merged and resolve the src/tools.mjs conflict while preserving #55’s send-validation and safeEcho behavior. Re-run CI after the rebase; I’ll do a focused re-review of the resolution.

[manisaigaddam]

Rebased onto current main after #55 (7491e88).

src/tools.mjs conflict is resolved. #55 is preserved:

• safeEcho on amount refusals (invalid / zero / negative)
• resolveSend still refuses those before the wallet
• /send with the wrong number of args still prints usage: /send <to> <mon> (scripted mode still fails)

Swap behavior is unchanged: spend policy, auto-best + y/N, confirm-click re-quote, Multicall3. Swap + policy + test/send-args.test.mjs pass locally.

Please re-review the resolution. Same PR, no new one.

[portdeveloper]

nice, lgtm

[portdeveloper]

#49 has landed and this branch now conflicts with current main. The reviewed swap work remains approved. Please rebase, preserve both features in the conflict resolution, and rerun CI; I will do a focused resolution check.

[manisaigaddam]

Rebased onto current main after #49 (2425c6c). Swap work is unchanged; both features are in the conflict resolution.

Kept from #49: /account, parseAccountIndex, safeEcho on a bad index, persisted accountIndex in state.json, derive/switch on the active Safe.

Kept from this PR: PuddleSwap swap, spend policy, auto-best + y/N, confirm-click re-quote, Multicall3, sendCalls.

Swap + policy + send-args + accounts unit tests pass locally. Same PR, no new one.

[portdeveloper]

lgtm, thanks

[portdeveloper]

can you fix the conflicts

[manisaigaddam]

Rebased onto current main (NFT work at 5600ae7) and resolved the conflicts. Same PR, no new one.

Kept all three:

• NFT from main: get_nfts / transfer_nft, Reservoir reads, ownership-checked safeTransferFrom
• Accounts from feat: multi-account support (issue #12) #49: /account, parseAccountIndex, persisted accountIndex
• This PR: PuddleSwap swap, spend policy on native-MON swaps, auto-best route + y/N, silent re-quote at confirm

Swap, policy, send-args, NFT, and related unit tests pass locally. CI should go green.

[portdeveloper]

lgtm, thanks