contract-preflight

合约预检

在不广播的情况下，针对主网实时状态对任意 Stacks 合约调用进行试运行。使用 stxer 的模拟引擎评估 Clarity 表达式、解码结果，并给出明确的通过／失败判定。如果模拟返回 (err ...) 或运行时错误，此技能会阻止广播并说明原因。

功能

在广播合约调用之前，此技能会创建模拟会话，针对当前链上状态运行你的 Clarity 表达式，并告知你调用会成功还是失败。不消耗 Gas。不更改链上状态。只给出判定：可以安全广播，或者不可以。

Secret Mars 在 1900 多轮自主运行中，每次合约调用前都会执行此项检查。采用这一模式后，交易中止次数为零。

命令

doctor

预检：检查 stxer API 是否可访问、能否创建模拟会话，以及运行时检测情况。

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

run --action=simulate

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

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

在单个会话中模拟一系列合约调用。状态会在各步骤之间延续——适用于第 2 步依赖第 1 步的多步骤 DeFi 操作。

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

无需额外软件包。使用 fetch() 和 commander。

安全说明

• 设计上只读。 此技能绝不会广播，只会进行模拟。
• 会话隔离。 每次模拟都在全新的 stxer 会话中运行。各次运行之间不会相互影响。
• 表达式长度限制。 上限为 2,000 个字符，以防滥用。
• 步骤限制。 每批最多 20 步，以防模拟失控。
• 超时。 每次 API 调用超时为 15 秒。超时后会正常失败。
• 无需私钥。 模拟使用发送方地址，而非签名密钥。
• 如实判定。 如果 Clarity 表达式返回 (err ...)，此技能会报告为不安全，不会粉饰结果。

输出约定

模拟（单次调用）

{
  "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
}

批量（多步骤）

{
  "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
}

模拟证明

以下模拟于 2026-04-10 在主网状态下运行，未进行广播：

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

这笔不可能完成的转账若在链上执行，会中止并浪费 Gas。模拟免费发现了这一问题。

架构

[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"

使用场景

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

限制

• 基于当前区块状态进行模拟。无法预测未来的状态变化（MEV、并发交易）。
• Stxer API 是第三方服务。如果服务不可用，此技能会报告故障，但无法进行模拟。
• 在单个会话中可以正确模拟具有副作用的复杂合约交互，但状态不会跨会话持久保存。
• 不验证后置条件——只检查 Clarity 返回值。

起源

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