contract-preflight

Contract Pre-Flight

ブロードキャストせずに、稼働中のメインネット状態に対して Stacks コントラクト呼び出しをドライランします。stxer のシミュレーションエンジンを使用して Clarity 式を評価し、結果をデコードして、明確な成功／失敗の判定を返します。シミュレーションが (err ...) またはランタイムエラーを返した場合、このスキルはブロードキャストをブロックし、その理由を説明します。

機能

コントラクト呼び出しをブロードキャストする前に、このスキルはシミュレーションセッションを作成し、現在のチェーン状態に対して Clarity 式を実行して、成功するか失敗するかを通知します。ガスは消費されません。オンチェーンの状態も変更されません。判定は「安全にブロードキャストできる」か「できない」かだけです。

エージェントに必要な理由

オンチェーンのトランザクション失敗はガスを消費し、目に見える形で中断します。残高不足で Zest への供給をブロードキャストするエージェント、誤ったプリンシパルにトークンを送金するエージェント、または期限切れのパラメーターを含む DAO 提案を送信するエージェントは、最初から必ず失敗するトランザクションに STX を無駄にします。このスキルは、そうした種類のエラーを完全に防ぎます。

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

1 つのセッション内で一連のコントラクト呼び出しをシミュレートします。状態は各ステップ間で引き継がれます。ステップ 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	zsbtc-v2-0 の get-balance tx-sender	(ok uint 276016)	安全
実行不可能な送金	（2 つ目のセッション）	sbtc-token の transfer u99999999	(err uint 1)	ブロック

この実行不可能な送金は、オンチェーンでは中断され、ガスを無駄にしていたはずです。シミュレーションなら、コストをかけずに検出できました。

アーキテクチャ

[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 ガバナンス： 提出前に提案パラメーターが有効であることを確認します。
• 複数ステップの処理： 1 つのセッションで、承認 → 送金 → 供給の一連の処理をシミュレートします。
• デバッグ： コントラクト呼び出しが失敗した場合、シミュレーションで再実行して、正確な Clarity エラーを確認します。

制限事項

• 現在のブロック状態に対してシミュレートします。将来の状態変化（MEV、同時に発生する tx）を予測することはできません。
• Stxer API はサードパーティーのサービスです。停止している場合、このスキルは障害を報告しますが、シミュレーションは実行できません。
• 副作用を伴う複雑なコントラクトのやり取りは、1 つのセッション内では正しくシミュレートされますが、セッションをまたいで状態が保持されることはありません。
• 事後条件は検証しません。Clarity の戻り値のみを検証します。

開発の経緯

AIBTC x Bitflow Skills Pay the Bills コンペティションの優勝作品です。 原作者：@secret-mars コンペティション PR：https://github.com/BitflowFinance/bff-skills/pull/258