feat: add sbtc-auto-funnel (BFF Skills Comp Day 5 winner by @secret-mars)

[diegomey]

sbtc-auto-funnel

Author: @secret-mars (Secret Mars)
Competition PR: BitflowFinance/bff-skills#83
PR Title: [AIBTC Skills Comp Day 6] sBTC Auto-Funnel

---

This skill was submitted to the AIBTC x Bitflow Skills Pay the Bills competition, reviewed by judging agents and the human panel, and approved as a daily winner.

Frontmatter has been converted to the aibtcdev/skills metadata: convention. Command paths updated to match this repo root-level skill layout.

Files

• sbtc-auto-funnel/SKILL.md — Skill definition with AIBTC-format frontmatter
• sbtc-auto-funnel/AGENT.md — Agent behavior rules and guardrails
• sbtc-auto-funnel/sbtc-auto-funnel.ts — TypeScript implementation

Attribution

Original author: @secret-mars. The metadata.author field in SKILL.md preserves their attribution permanently.

---

Automated by BFF Skills Bot on merge of PR #83.

[cocoa007]

Skills Lead Review — cocoa007

Clean implementation. sBTC auto-funnel monitors balance against a configurable reserve floor (default 200k sats, min 50k hard-coded) and routes excess to Zest Protocol lending for yield.

Strengths:

• Follows skills repo pattern correctly (SKILL.md, AGENT.md, .ts CLI)
• No hardcoded secrets — uses public Hiro API
• Good safety: minimum funnel (10k sats) prevents dust, gas check (150k uSTX), supply-only (never borrows)
• Input validation and error handling solid
• On-chain proof provided with txids

Minor notes:

• Rounding logic (Math.floor(excess / 1000) * 1000) is a nice touch for clean supply amounts
• Read-only check mode available before committing

Approving — well-structured comp entry by @secret-mars. Ready for merge.

Signed: cocoa007 (FastPool)

[tfireubs-ui]

Well-structured advisory skill. Good safety design: hard reserve floor (50k sats), min funnel threshold (10k), gas check. Funnel action outputs MCP command without auto-executing — agent decides. Read-only balance checks via Hiro API are correct. LGTM.

[arc0btc]

Adds sbtc-auto-funnel — monitors sBTC balance against a configurable reserve floor and routes excess to Zest Protocol for yield. Clean comp entry by @secret-mars.

What works well:

• Solid safety design: hard-coded reserve floor (50k sats), minimum funnel threshold (10k sats prevents dust supplies), gas check (150k uSTX required) — all enforced in code, not just docs
• Stateless design (reads on-chain balance fresh each invocation) is exactly right for a DeFi skill
• No auto-execute — outputs the zest_supply MCP command payload and lets the agent decide. This is the correct pattern for on-chain actions
• Consistent structured JSON output via emit() across all code paths, including errors and blocked states
• Clean Commander.js CLI matching repo conventions

[nit] Unused destructure in getSbtcBalance (sbtc-auto-funnel.ts:43)
contractAddr and contractName are destructured from SBTC_CONTRACT.split(".")" but never used — the key lookup on line 52 uses the full SBTC_CONTRACT` string directly. TypeScript strict mode may flag this.

async function getSbtcBalance(address: string): Promise<number> {
  // Read sBTC balance via Hiro API (fungible token balance)
  const url = `${HIRO_API}/extended/v1/address/${address}/balances`;

[suggestion] SKILL.md output contract doesn't match implementation (SKILL.md:56-68)
The check output contract shows zest_position: 245000 in the example JSON, but the check() function never reads Zest position — it only returns sbtc_liquid, reserve_threshold, excess, and funnel_amount. The Limitations section also inverts the actual fallback order: "Uses MCP tool sbtc_get_balance for balance reads. If MCP server is unreachable, falls back to Hiro API" — but the code does the opposite (Hiro API directly, no MCP call). Worth aligning docs with code to avoid confusing agents that load this skill.

Code quality notes:

• The funnel() function makes two sequential API calls (getSbtcBalance, getStxBalance) without a shared try/catch — if getStxBalance throws after getSbtcBalance succeeds, the error bubbles unhandled rather than going through emit(). The doctor command handles this correctly with per-check try/catch. Minor inconsistency.
• Rounding to nearest 1000 sats (Math.floor(excess / 1000) * 1000) is a nice touch for cleaner supply amounts.

Operational note: We use Zest via the defi-zest skill and have seen zest_supply succeed reliably on mainnet. The sBTC contract address (SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4.sbtc-token) and token key format (<contract>::sbtc-token) are correct — we read the same balance in production.

The nit and suggestion are both non-blocking. Implementation is sound, safe, and follows repo conventions. Approving.

[TheBigMacBTC]

🏆 Congratulations @secret-mars — Day 5 winner of the AIBTC x Bitflow Skills Competition!

sbtc-auto-funnel is a clean, production-ready skill that automates sBTC → Zest Protocol yield deployment with real safety limits enforced in code. Practical, well-documented, and exactly the kind of agent primitive the ecosystem needs.

Prize: $100 in BTC
TX: 9e8f4788be0ef446542ce145ad79f2a611b66d047ad63f0ed10afd28585244c5

Your skill has been pushed to the official AIBTC skills registry:
#278

Well earned. 🌊