feat: add hodlmm-execution-envelope skill#533
Open
giwaov wants to merge 1 commit into
Open
Conversation
✅ Validation PassedSkill: All checks passed. This submission is ready for review. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Skill Submission
Skill name: hodlmm-execution-envelope
Category: Infrastructure
HODLMM integration? Yes
What it does
Builds deterministic, safety-gated HODLMM execution envelopes from live Bitflow pool/bin state, quote previews, and wallet balances. Instead of broadcasting transactions directly, it packages idempotent JSON plans with bin placements, quote-backed shortfall routing, strict/simple execution modes, cooldowns, TTLs, and hardcoded risk caps so downstream agents can execute without guessing.
On-chain proof
Live mainnet output captured against Bitflow HODLMM
dlmm_3and Hiro mainnet endpoints on April 24, 2026.Successful live preview output:
intent_id:b7512f1d5081f3c818e716a304f90ab8dlmm_3316SP3ESW1QCNQPVXJDGQWT7E45RDCH38QBK9HEJSX4XUSDCXoutput for the shortfall legAdditional guardrail verification:
0 STXINSUFFICIENT_STX_RESERVEinstead of generating a spendable envelopeRegistry compatibility checklist
SKILL.mdusesmetadata:nested frontmatter (not flat keys)AGENT.mdstarts with YAML frontmatter (name,skill,description)tagsandrequiresare comma-separated quoted strings, not YAML arraysuser-invocableis the string"false", not a booleanentrypath is repo-root-relative (noskills/prefix)metadata.authorfield is present with your GitHub username{ "error": "descriptive message" }formatSmoke test results
doctor output
{ "status": "success", "action": "doctor", "data": { "checks": { "bitflow_app": "ok", "bitflow_quotes": "ok", "hiro": "ok", "wallet_index": "ok", "state_dir": "ok" }, "ready": true, "mode_support": [ "strict", "simple" ], "spread_support": [ "narrow", "balanced", "wide" ] }, "error": null }run output
{ "status": "success", "action": "run", "data": { "skill": "hodlmm-execution-envelope", "intent_id": "b7512f1d5081f3c818e716a304f90ab8", "idempotency_key": "aa396144e40cbf5311a73b071147ef9fd60da9fe9193843b72991edbf696b1db", "created_at": "2026-04-24T15:30:52.357Z", "expires_at": "2026-04-24T15:50:52.357Z", "sealed": false, "network": "mainnet", "mode": "simple", "spread": "balanced", "pool": { "pool_id": "dlmm_3", "active_bin_id": 316, "tvl_usd": 1133349.16, "apr_24h": 18.46, "token_x": { "symbol": "STX", "decimals": 6, "priceUsd": 0.23085797, "contractId": "SM1793C4R5PZ4NS4VQ4WMP7SKKYVH8JZEWSZ9HCCR.token-stx-v-1-2" }, "token_y": { "symbol": "USDCX", "decimals": 6, "priceUsd": 0.99821041, "contractId": "SP120SBRBQJ00MCWS7TM5R8WJNTTKD5K0HFRC2CNE.usdcx" } }, "wallet": { "stx_address": "SP3ESW1QCNQPVXJDGQWT7E45RDCH38QBK9HEJSX4X", "wallet_name": "manual-address", "source": "arg", "balances": { "stx": 197.610187, "usdcx": null } }, "safety_gates": { "amount_cap_ok": true, "reserve_floor_ok": true, "pool_tvl_ok": true, "position_complexity_ok": true, "strict_ttl_ok": true, "quote_price_impact_ok": true }, "target_budget": { "input_asset": "STX", "input_amount_stx": 25, "estimated_budget_usd": 5.77 }, "placement_plan": [ { "placement_mode": "simple", "offset_from_active": -2, "offset": -2, "bin_price": 22801431, "weight_bps": 1000, "usd_allocation": 0.58, "token_rule": "USDCX-only", "token_x_symbol": "STX", "token_y_symbol": "USDCX", "token_x_usd": 0, "token_y_usd": 0.58, "token_x_estimated_units": 0, "token_y_estimated_units": 0.57817963, "reserve_x": 0, "reserve_y": 978845898, "is_active_bin": false }, { "placement_mode": "simple", "offset_from_active": -1, "offset": -1, "bin_price": 22824233, "weight_bps": 2000, "usd_allocation": 1.15, "token_rule": "USDCX-only", "token_x_symbol": "STX", "token_y_symbol": "USDCX", "token_x_usd": 0, "token_y_usd": 1.15, "token_x_estimated_units": 0, "token_y_estimated_units": 1.15635926, "reserve_x": 0, "reserve_y": 1011368145, "is_active_bin": false }, { "placement_mode": "simple", "offset_from_active": 0, "offset": 0, "bin_price": 22847057, "weight_bps": 4000, "usd_allocation": 2.31, "token_rule": "split-active-bin", "token_x_symbol": "STX", "token_y_symbol": "USDCX", "token_x_usd": 1.15, "token_y_usd": 1.15, "token_x_estimated_units": 5, "token_y_estimated_units": 1.15635926, "reserve_x": 77252809, "reserve_y": 1015428749, "is_active_bin": true }, { "placement_mode": "simple", "offset_from_active": 1, "offset": 1, "bin_price": 22869904, "weight_bps": 2000, "usd_allocation": 1.15, "token_rule": "STX-only", "token_x_symbol": "STX", "token_y_symbol": "USDCX", "token_x_usd": 1.15, "token_y_usd": 0, "token_x_estimated_units": 5, "token_y_estimated_units": 0, "reserve_x": 4585201995, "reserve_y": 0, "is_active_bin": false }, { "placement_mode": "simple", "offset_from_active": 2, "offset": 2, "bin_price": 22892774, "weight_bps": 1000, "usd_allocation": 0.58, "token_rule": "STX-only", "token_x_symbol": "STX", "token_y_symbol": "USDCX", "token_x_usd": 0.58, "token_y_usd": 0, "token_x_estimated_units": 2.5, "token_y_estimated_units": 0, "reserve_x": 4573823958, "reserve_y": 0, "is_active_bin": false } ], "shortfall_plan": { "token_x_target_units": 12.47520283, "token_y_target_units": 2.88516326, "token_x_shortfall_units": 0, "token_y_shortfall_units": 2.88516326, "token_x_shortfall_usd": 0, "token_y_shortfall_usd": 2.88 }, "quote_legs": [ { "target_symbol": "USDCX", "shortfall_units": 2.88516326, "shortfall_usd": 2.88, "input_symbol": "STX", "quote_request": { "input_token": "SM1793C4R5PZ4NS4VQ4WMP7SKKYVH8JZEWSZ9HCCR.token-stx-v-1-2", "output_token": "SP120SBRBQJ00MCWS7TM5R8WJNTTKD5K0HFRC2CNE.usdcx", "amount_in": "12475203", "slippage_tolerance": 0.75 }, "preview": { "amountOutAtomic": "2841666", "amountOutDisplay": 2.841666, "priceImpactPct": null, "routeCount": 1, "rawRoute": null } } ], "existing_position_bins": [], "execution_sequence": [ "Refresh quote legs at execution time if envelope has expired.", "Acquire only the documented shortfall assets from STX budget.", "Apply the placement plan exactly as listed.", "Use offsets from the active bin to tolerate small market movement.", "Do not exceed the documented per-bin weights or the quoted price-impact cap." ], "sealed_path": null, "preview_only": true, "confirm_required_for_seal": true }, "error": null }Security notes
Read-only planning skill: no transactions are broadcast and no funds are moved by this skill. It is mainnet-only, wallet-aware, and enforces hardcoded safety gates for STX budget caps, reserve floors, pool TVL floors, position complexity, TTL in strict mode, per-bin concentration, cooldown reuse, and quote price-impact checks.