feat(hodlmm-capital-router-v2): HODLMM Capital Router v2 with real on-chain execution

skills/hodlmm-capital-router-v2/.gitignore

@@ -0,0 +1,5 @@
+node_modules/
+*.js
+package-lock.json
+tsconfig.json
+package.json

skills/hodlmm-capital-router-v2/AGENT.md

@@ -0,0 +1,64 @@
+---
+name: hodlmm-capital-router-v2-agent
+skill: hodlmm-capital-router-v2
+description: "Routes sBTC between HODLMM and Zest based on live APY with real on-chain execution, spend limits, and txid proof."
+---
+
+# Agent Behavior — HODLMM Capital Router v2
+
+## Decision order
+1. Run `doctor` first. If wallet unlock fails or balance insufficient, STOP.
+2. Run `compare` to fetch live APY from both protocols.
+3. If delta < 0.5% → hold, no action needed.
+4. Confirm routing intent with operator before executing.
+5. Run `run --amount <sats>` to execute on-chain.
+6. Parse JSON output, confirm txid on Hiro explorer, log result.
+
+## Guardrails
+- NEVER move more than 100,000 satoshis per invocation.
+- NEVER route if APY delta is below 0.5%.
+- NEVER proceed if sBTC balance is insufficient.
+- NEVER retry a failed transaction automatically.
+- NEVER expose WALLET_PASSWORD in logs or output.
+- Always require explicit operator confirmation before write.
+- Default to blocked when intent is ambiguous.
+
+## Routing logic
+- HODLMM APY > Zest APY by more than 0.5% → supply to HODLMM
+- Zest APY > HODLMM APY by more than 0.5% → supply to Zest via zest_supply
+- Delta below 0.5% → hold, no routing needed
+
+## Refusal conditions
+- Amount > 100,000 sats → REFUSE with EXCEEDS_SPEND_LIMIT
+- Insufficient sBTC → REFUSE with INSUFFICIENT_BALANCE
+- APY delta < 0.5% → REFUSE with DELTA_TOO_SMALL
+- Wallet unlock failed → REFUSE with WALLET_UNAVAILABLE
+- WALLET_PASSWORD not set → REFUSE with MISSING_PASSWORD
+
+## Output contract
+\`\`\`json
+{
+  "status": "success | error | blocked",
+  "action": "next recommended action",
+  "data": {
+    "txid": "0x...",
+    "protocol": "zest | hodlmm",
+    "hodlmm_apy_pct": 4.0,
+    "zest_apy_pct": 3.5,
+    "apy_delta_pct": 0.5,
+    "amount_sats": 1000,
+    "tx_status": "pending",
+    "explorer_url": "https://explorer.hiro.so/txid/..."
+  },
+  "error": { "code": "", "message": "", "next": "" }
+}
+\`\`\`
+
+## On error
+- Log full error payload.
+- Do not retry silently.
+- Surface to operator with action guidance.
+
+## Cooldown
+- 60 seconds minimum between executions.
+- Maximum 3 routing actions per session without reconfirmation.

skills/hodlmm-capital-router-v2/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: hodlmm-capital-router-v2
+description: "Compares live HODLMM LP yield vs Zest lending rate and routes sBTC capital to the highest-yielding protocol with real on-chain execution and txid proof."
+metadata:
+  author: "jnrspaco"
+  author-agent: "Galactic Orbit"
+  user-invocable: "false"
+  arguments: "doctor | compare | run"
+  entry: "hodlmm-capital-router-v2/hodlmm-capital-router-v2.ts"
+  requires: "wallet, signing, settings, AIBTC_WALLET_ID, WALLET_PASSWORD"
+  tags: "defi, write, mainnet-only, requires-funds, l2"
+---
+
+# HODLMM Capital Router v2
+
+## What it does
+Fetches live APY from Bitflow HODLMM sBTC pool and Zest Protocol lending
+market. Compares rates and routes sBTC capital to the higher-yielding
+protocol. Executes real on-chain transactions via AIBTC MCP wallet and
+returns verified txids as proof. v2 adds real execution — not just params.
+
+## Why agents need it
+Agents managing sBTC need to continuously optimize yield. This skill
+implements the full capital routing loop with real on-chain execution:
+compare HODLMM vs Zest APY → route to highest yield → return txid proof.
+
+## Safety notes
+- This skill WRITES to chain and moves real funds.
+- Maximum capital movement: 100,000 satoshis per invocation.
+- Minimum APY delta to trigger routing: 0.5%.
+- Maximum slippage: 1%.
+- Requires WALLET_PASSWORD environment variable.
+- Mainnet only — real funds at risk.
+
+## Commands
+
+### doctor
+Unlocks wallet, checks sBTC balance, fetches live APY from both protocols.
+\`\`\`bash
+bun run hodlmm-capital-router-v2/hodlmm-capital-router-v2.ts doctor
+\`\`\`
+
+### compare
+Fetches live APY from both protocols without executing.
+\`\`\`bash
+bun run hodlmm-capital-router-v2/hodlmm-capital-router-v2.ts compare
+\`\`\`
+
+### run
+Routes capital to highest-yielding protocol and returns real txid.
+\`\`\`bash
+bun run hodlmm-capital-router-v2/hodlmm-capital-router-v2.ts run --amount 1000
+\`\`\`
+Amount in satoshis. Max: 100,000 satoshis (0.001 sBTC).
+
+## Output contract
+\`\`\`json
+{
+  "status": "success | error | blocked",
+  "action": "what the agent should do next",
+  "data": {
+    "txid": "0xabc123...",
+    "protocol": "zest | hodlmm",
+    "hodlmm_apy_pct": 4.0,
+    "zest_apy_pct": 3.5,
+    "apy_delta_pct": 0.5,
+    "amount_sats": 1000,
+    "tx_status": "pending",
+    "explorer_url": "https://explorer.hiro.so/txid/..."
+  },
+  "error": null
+}
+\`\`\`
+
+## Known constraints
+- Max movement: 100,000 satoshis per invocation.
+- Min APY delta: 0.5% to trigger routing.
+- Requires WALLET_PASSWORD env var.
+- Uses Bitflow ticker for HODLMM APY.
+- Uses Hiro read-only call for Zest APY.