如何调试合约

---

UTXO_Compiler 内置了一个交互式命令行调试器，在本地 BVM 模拟器上单步执行编译后的字节码。你可以设置断点、查看栈状态、跟踪函数调用，也可以加载真实交易数据来模拟链上环境。

---

启动调试器

# 基本启动
./utxo_compiler my_contract.ct --debug

# 合约用到了子作用域副栈操作（--asa 模式）
./utxo_compiler my_contract.ct --debug --asa

启动调试器后先要选择语言：

选择 CLI 语言 / Select CLI language [zh/en] (默认 default: zh):

---

选择调试目标

如果合约有多个公有函数，调试器会提示选择：

=====================================
可调试的函数列表:
=====================================
[1] getCountFromPreTX (public, 1 个参数)
[2] verifyCurrentTX (public, 1 个参数)

请选择要调试的函数 (输入编号 1-2, 或直接回车跳过): _

• 输入编号，只调试该函数
• 直接回车，依次对所有公有函数输入参数并调试

接着输入函数参数：

=====================================
调试函数: getCountFromPreTX (public)
需要为以下参数提供初始值:
=====================================

参数 1/1: pretx (结构体: PreTX, 17 个字段)

参数输入格式：

类型	输入方式
整数	42、-10、0x1a（十六进制整数）
hex 字节	0x1234abcd
字符串	"hello"（用引号包围）
默认值	直接回车使用类型默认值

---

命令参考

选择待调试函数和输入参数后出现 REPL 提示符：

=====================================
已将 17 个参数压入主栈
=====================================
=====================================
  UTXO_Compiler Debugger v1.0
=====================================
加载: ../../contract_file/counter.ct
输入 'help' 查看可用命令。

(apc-debug) _

输入 help 查看所有可用命令。

执行控制

命令	简写	说明
run	r	开始执行（或从当前状态继续执行）
continue	c	从断点或暂停处继续
step	s	单步进入（遇到函数调用时进入）
next	n	单步跳过（不进入函数调用，将整个调用当作一步）
finish	f	跳出当前函数，执行到调用方的下一行
reset	—	将 VM 完全重置到进入 REPL 时的初始状态
pause	—	暂停正在运行的执行

断点管理

命令	简写	说明
break <行号>	b <N>	在指定源码行设置断点
break <函数名>	b <name>	在函数入口设置断点
delete <断点ID>	d <ID>	删除指定断点
disable <断点ID>	—	禁用断点（不触发，但保留）
enable <断点ID>	—	重新启用断点
info breakpoints	info bp	列出所有断点及其状态

状态查看

命令	简写	说明
list [行号]	l	显示源代码，默认以当前执行行为中心
stack	—	显示主栈和副栈的当前内容
backtrace	bt	显示函数调用栈
bytecode [N]	bc [N]	显示当前执行位置附近的字节码，N 为上下文行数

交易数据

命令	说明
settxfile <路径>	从 JSON 文件加载交易数据（用于 BVM.* 字段的模拟）
showtx	显示当前已加载的交易数据

其他

命令	说明
help / h	显示命令帮助
quit / q / exit	退出调试器
clear	清屏

---

生成调试信息（不启动调试器）

如果只需要生成调试信息文件用于其他工具，使用 -d 标志：

./utxo_compiler my_contract.ct -d

调试信息包含源码行号到字节码偏移的映射，以及函数符号表，供第三方工具分析。

---

下一步

• 教程一：P2PKH 合约入门 — 用调试器跟踪一个真实签名合约

---

🇬🇧 English version