contract-preflight

# Contract Pre-Flight Dry-run any Stacks contract call against live mainnet state without broadcasting. Uses stxer's simulation engine to evaluate Clarity expressions, decode results, and give a clear pass/fail verdict. If the simulation returns `(err ...)` or a runtime error, the skill blocks broadcast and explains why. ## What it does Before you broadcast a contract call, this skill creates a simulation session, runs your Clarity expression against the current chain state, and tells you whether it would succeed or fail. No gas spent. No on-chain state changed. Just a verdict: safe to broadcast, or not. ## Why agents need it On-chain transaction failures cost gas and abort visibly. An agent that broadcasts a Zest supply with insufficient balance, a token transfer to a wrong principal, or a DAO proposal with expired parameters wastes STX on a transaction that was always going to fail. This skill eliminates that category of error entirely. Secret Mars runs this check before every contract call across 1900+ cycles of autonomous operation. Zero aborted transactions since adopting the pattern. ## Commands ### `doctor` Pre-flight checks: stxer API reachability, simulation session creation, runtime detection. ```bash bun run contract-preflight/contract-preflight.ts doctor ``` ### `run --action=simulate` Simulate a single contract call. Returns decoded Clarity result and broadcast recommendation. ```bash bun run contract-preflight/contract-preflight.ts run \ --action=simulate \ --sender <YOUR_STACKS_ADDRESS> \ --contract SP2VCQJGH7PHP2DJK7Z0V48AGBHQAW3R3ZW1QF4N.zsbtc-v2-0 \ --expression '(contract-call? .zsbtc-v2-0 get-balance tx-sender)' ``` ### `run --action=batch` Simulate a sequence of contract calls in a single session. State carries across steps — useful for multi-step DeFi operations where step 2 depends on step 1. ```bash bun run contract-preflight/contract-preflight.ts run \ --action=batch \ --sender <YOUR_STACKS_ADDRESS> \ --steps '[ {"contract":"SP2VCQJGH7PHP2DJK7Z0V48AGBHQAW3R3ZW1QF4N.zsbtc-v2-0","expression":"(contract-call? .zsbtc-v2-0 get-balance tx-sender)"}, {"contract":"SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4.sbtc-token","expression":"(contract-call? .sbtc-token get-balance tx-sender)"} ]' ``` ### `install-packs` No additional packages required. Uses `fetch()` and `commander`. ## Safety notes - **Read-only by design.** This skill never broadcasts. It simulates only. - **Session isolation.** Each simulation runs in a fresh stxer session. No cross-contamination between runs. - **Expression length limit.** Capped at 2,000 characters to prevent abuse. - **Step limit.** Maximum 20 steps per batch to prevent runaway simulations. - **Timeout.** 15-second timeout per API call. Fails cleanly on timeout. - **No private keys needed.** Simulation uses sender address, not signing keys. - **Honest verdict.** If the Clarity expression returns `(err ...)`, the skill reports it as unsafe. No sugar-coating. ## Output contract ### Simulate (single call) ```json { "status": "success | error", "action": "simulate", "data": { "session_id": "d1c27b645459c702feae3a7a637a4777", "result": { "outcome": "ok", "decoded": "(ok uint 276016)", "raw_hex": "070100000000000000000000000000043630", "safe_to_broadcast": true }, "recommendation": "Simulation passed. Safe to broadcast this contract call." }, "error": null } ``` ### Batch (multi-step) ```json { "status": "success | error", "action": "batch", "data": { "session_id": "abc123", "total_steps": 2, "passed": 2, "failed": 0, "results": [ {"step": 0, "outcome": "ok", "decoded": "(ok uint 276016)", "safe": true}, {"step": 1, "outcome": "ok", "decoded": "(ok uint 204206)", "safe": true} ], "recommendation": "All steps passed. Safe to broadcast the transaction sequence." }, "error": null } ``` ## Simulation Proof These simulations were run on mainnet state (2026-04-10) without broadcasting: | Test | Session | Expression | Result | Verdict | |------|---------|-----------|--------|---------| | Balance read | d1c27b645459c702feae3a7a637a4777 | `get-balance tx-sender` on zsbtc-v2-0 | `(ok uint 276016)` | Safe | | Impossible transfer | (second session) | `transfer u99999999` on sbtc-token | `(err uint 1)` | Blocked | The impossible transfer would have aborted on-chain and wasted gas. The simulation caught it for free. ## Architecture ``` [Agent wants to call contract] ↓ [contract-preflight simulate] ↓ [Create stxer session] → [Eval Clarity expression against mainnet state] ↓ ↓ [Ok result] [Err result] ↓ ↓ "Safe to broadcast" "DO NOT broadcast" ``` ## Use cases - **DeFi operations:** Verify Zest supply/withdraw, Bitflow swaps, ALEX trades before broadcast. - **Token transfers:** Confirm balance sufficient and recipient valid before sending. - **DAO governance:** Check proposal parameters are valid before submission. - **Multi-step sequences:** Simulate approve → transfer → supply chains in one session. - **Debugging:** When a contract call fails, replay it in simulation to see the exact Clarity error. ## Limitations - Simulates against current block state. Cannot predict future state changes (MEV, concurrent txs). - Stxer API is a third-party service. If it's down, the skill reports the outage but cannot simulate. - Complex contract interactions with side effects are simulated correctly within one session, but cross-session state does not persist. - Does not validate post-conditions — only the Clarity return value. ## Origin Winner of AIBTC x Bitflow Skills Pay the Bills competition. Original author: @secret-mars Competition PR: https://github.com/BitflowFinance/bff-skills/pull/258