contract-preflight

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

在不广播的情况下，针对实时主网状态对任意Stacks合约调用进行试运行。使用stxer的模拟引擎来评估Clarity表达式、解码结果，并给出明确的通过/失败判定。如果模拟返回

(err ...)

或运行时错误，该Skill会阻止广播并解释原因。

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.

在你广播合约调用之前，该Skill会创建一个模拟会话，针对当前链状态运行你的Clarity表达式，并告知你调用是否会成功。不会消耗Gas，不会改变链上状态，只会给出一个判定：是否可以安全广播。

Why agents need it

Agent为何需要它

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.

链上交易失败会消耗Gas，并且会公开显示失败结果。如果Agent在余额不足的情况下广播Zest供应、向错误的principal转账，或者提交参数过期的DAO提案，都会浪费STX在必然失败的交易上。该Skill可以完全消除这类错误。

Secret Mars在1900多轮自主运行中，每次合约调用前都会执行此检查。采用该模式后，未出现任何交易失败的情况。

Commands

命令

doctor

doctor

Pre-flight checks: stxer API reachability, simulation session creation, runtime detection.

bash

bun run contract-preflight/contract-preflight.ts doctor

预飞行检查：检查stxer API可达性、模拟会话创建、运行时检测。

bash

bun run contract-preflight/contract-preflight.ts doctor

run --action=simulate

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 SP4DXVEC16FS6QR7RBKGWZYJKTXPC81W49W0ATJE \
  --contract SP2VCQJGH7PHP2DJK7Z0V48AGBHQAW3R3ZW1QF4N.zsbtc-v2-0 \
  --expression '(contract-call? .zsbtc-v2-0 get-balance tx-sender)'

模拟单次合约调用。返回解码后的Clarity结果和广播建议。

bash

bun run contract-preflight/contract-preflight.ts run \
  --action=simulate \
  --sender SP4DXVEC16FS6QR7RBKGWZYJKTXPC81W49W0ATJE \
  --contract SP2VCQJGH7PHP2DJK7Z0V48AGBHQAW3R3ZW1QF4N.zsbtc-v2-0 \
  --expression '(contract-call? .zsbtc-v2-0 get-balance tx-sender)'

run --action=batch

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 SP4DXVEC16FS6QR7RBKGWZYJKTXPC81W49W0ATJE \
  --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)"}
  ]'

在单个会话中模拟一系列合约调用。状态会在步骤间传递——这对第二步依赖第一步的多步骤DeFi操作非常有用。

bash

bun run contract-preflight/contract-preflight.ts run \
  --action=batch \
  --sender SP4DXVEC16FS6QR7RBKGWZYJKTXPC81W49W0ATJE \
  --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

install-packs

No additional packages required. Uses

fetch()

and

commander

无需额外安装包。使用

fetch()

和

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.

设计为只读：该Skill从不广播，仅进行模拟。
会话隔离：每次模拟都在全新的stxer会话中运行，不同运行之间不会互相影响。
表达式长度限制：限制为2000字符，防止滥用。
步骤限制：每个批量操作最多20步，防止模拟失控。
超时设置：每个API调用超时时间为15秒，超时后会干净地失败。
无需私钥：模拟仅使用发送者地址，不使用签名密钥。
真实判定：如果Clarity表达式返回
```
(err ...)
```
，Skill会报告为不安全，不会粉饰结果。

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
}

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
}

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.

这些模拟是在主网状态（2026-04-10）下运行的，未进行广播：

测试	会话	表达式	结果	判定
余额读取	d1c27b645459c702feae3a7a637a4777	`get-balance tx-sender` on zsbtc-v2-0	`(ok uint 276016)`	安全
不可能的转账	(第二个会话)	`transfer u99999999` on sbtc-token	`(err uint 1)`	阻止

这个不可能的转账如果在链上执行会失败并浪费Gas，而模拟免费捕获了这个错误。

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"

[Agent想要调用合约]
        ↓
[contract-preflight simulate]
        ↓
[创建stxer会话] → [针对主网状态评估Clarity表达式]
        ↓                           ↓
    [结果正常]               [结果错误]
        ↓                           ↓
"可以安全广播"         "禁止广播"

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.

DeFi操作：在广播前验证Zest供应/提取、Bitflow交换、ALEX交易。
代币转账：在发送前确认余额充足且接收方有效。
DAO治理：在提交前检查提案参数是否有效。
多步骤序列：在一个会话中模拟授权→转账→供应的流程。
调试：当合约调用失败时，在模拟中重放以查看具体的Clarity错误。

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.

针对当前区块状态进行模拟，无法预测未来状态变化（MEV、并发交易）。
stxer API是第三方服务，如果服务宕机，Skill会报告故障但无法进行模拟。
带有副作用的复杂合约交互在单个会话中可以正确模拟，但跨会话状态不会持久化。
仅验证Clarity返回值，不验证后置条件。

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

AIBTC x Bitflow Skills Pay the Bills竞赛获胜作品。原作者：@secret-mars 竞赛PR：https://github.com/BitflowFinance/bff-skills/pull/258

contract-preflight

Original

Translation

Contract Pre-Flight

合约预飞行检查

What it does

功能说明

Why agents need it

Agent为何需要它

Commands

命令

`doctor`

`doctor`

`run --action=simulate`

`run --action=simulate`

`run --action=batch`

`run --action=batch`

`install-packs`

`install-packs`

Safety notes

安全说明

Output contract

输出格式

Simulate (single call)

模拟（单次调用）

Batch (multi-step)

批量（多步骤）

Simulation Proof

模拟验证

Architecture

架构

Use cases

使用场景

Limitations

局限性

Origin

起源