# 智能合约学习计划

本文面向具备基本编程能力、但刚接触 UTXO 智能合约与栈式虚拟机的学习者。学习节奏按一到两天一次安排，约两周完成。最终目标是理解 UTXO 合约的基本模型，能够阅读和编写简单合约，理解锁定/解锁脚本、ABI、字节码、调试流程、测试思路与常见错误排查方法。

## 参考资料

- 资料来源：[https://docs.utxocompiler.com/](https://docs.utxocompiler.com/)
- [概述](https://docs.utxocompiler.com/zh/overview)
- [安装](https://docs.utxocompiler.com/zh/installation)
- [比特币基础](https://docs.utxocompiler.com/zh/bitcoin-basics)
- [如何编写合约](https://docs.utxocompiler.com/zh/how-to-write-a-contract)
- [如何测试合约](https://docs.utxocompiler.com/zh/how-to-test-a-contract)
- [如何调试合约](https://docs.utxocompiler.com/zh/how-to-debug-a-contract)
- [如何部署与调用合约](https://docs.utxocompiler.com/zh/how-to-deploy-and-call-a-contract)
- [教程一：P2PKH 合约入门](https://docs.utxocompiler.com/zh/tutorials/tutorial-1-p2pkh)
- [教程二：Counter 合约实战](https://docs.utxocompiler.com/zh/tutorials/tutorial-2-counter)
- [副栈与多函数协作](https://docs.utxocompiler.com/zh/advanced/altstack-and-multi-function)
- [所有权系统](https://docs.utxocompiler.com/zh/advanced/ownership-system)
- [语言语法规范](https://docs.utxocompiler.com/zh/references/language-specification)
- [内置函数参考](https://docs.utxocompiler.com/zh/references/builtin-functions)
- [内置对象参考](https://docs.utxocompiler.com/zh/references/builtin-objects)
- [调试器用户手册](https://docs.utxocompiler.com/zh/references/debugger_user_manual)

## 使用说明

- 建议每次学习后都保留三类产物：练习合约、编译结果、调试或测试记录。
- 学习时优先完成小而明确的练习，再逐步增加状态、签名、哈希和交易上下文相关内容。
- 如果教程、工具或标准库版本之间存在差异，以实际使用环境中的文档和函数签名为准。
- 真实链上部署、广播和签名构造通常依赖钱包、节点、SDK 或交易构造工具，入门阶段可先聚焦合约语义、编译输出和本地验证。

## 学习计划

| 时间 | 学习主题 | 核心知识点 | 推荐阅读方向 | 实操练习 | 命令行练习 | 调试练习 | 本次验收标准 |
|---|---|---|---|---|---|---|---|
| 第 1 天 | UTXO、栈式虚拟机与工具链 | UTXO、输入、输出、locking script、unlocking script、脚本拼接执行、主栈、副栈、编译器、调试器、标准库 | UTXO 基础、脚本执行模型、安装指南、工具命令说明 | 手动画出一笔交易如何花费旧 UTXO 并创建新 UTXO；准备本地学习环境 | 查看版本、帮助信息和基础命令参数 | 纸面推演签名和公钥进入主栈后，P2PKH 如何依次验证公钥哈希与签名 | 能说明合约描述的是一个 UTXO 在什么条件下可以被花费，并能说明编译器、调试器和标准库的职责 |
| 第 2 天 | 第一个合约与基础语法 | 合约声明、公有函数、返回值、缩进、显式类型、单文件合约规则 | 合约语言入门、基础语法 | 编写一个永远通过的合约和一个简单比较合约，例如校验两个整数是否相等 | 编译练习合约并查看输出文件 | 进入调试器，练习运行、单步执行和查看栈 | 能编译简单合约，并能在输出中找到 ABI、锁定脚本和汇编信息 |
| 第 4 天 | 类型系统、函数、结构体与所有权 | 整数、字符串、十六进制、布尔、地址、定长字节、结构体、固定长度数组、字段访问、私有函数、变量消耗、数据复制 | 类型系统、函数、结构体、所有权系统、语言规范 | 编写含结构体、数组字段和私有辅助函数的练习合约；故意写一个重复使用变量的错误合约，再用复制操作修复 | 编译类型练习、错误合约和修复合约 | 观察结构体参数压栈、字段访问和数据复制后的执行差异 | 能说明数组长度约束、字段访问对数据使用方式的影响，并能判断什么时候必须复制数据 |
| 第 6 天 | 标准库与 P2PKH 合约 | 哈希、哈希比对、签名校验、成员变量、公钥哈希、解锁参数 | 标准库说明、P2PKH 教程 | 手写一份 P2PKH 合约；再用标准库函数改写 | 编译 P2PKH 练习合约，处理标准库导入问题 | 在调试器中练习按函数断点、运行、单步和查看栈 | 能读懂解锁参数中签名和公钥的顺序，能说明公钥哈希失败与签名失败的区别 |
| 第 8 天 | 编译输出、ABI、字节码与调试器 | 元数据、结构体信息、ABI、函数列表、锁定脚本、解锁脚本、参数顺序、断点、运行、继续、单步、回溯、查看字节码 | 编译输出说明、测试说明、调试器使用手册 | 对比两个不同合约的编译结果；做一次完整调试记录，包括断点、单步和栈快照 | 查看 JSON、搜索 ABI 和脚本字段，练习帮助、断点列表、重置和继续执行等命令 | 定位某个哈希比对或签名校验失败点，并把当前位置附近的字节码与汇编输出对应 | 能说明 ABI 是解锁参数约定，锁定脚本是写入输出中的验证逻辑，并能定位常见验证失败点 |
| 第 10 天 | 状态合约基础 | 成员变量、尾部状态、父交易、当前交易、交易哈希、状态递增、状态可信性 | 状态合约教程、部署与调用说明 | 阅读一个计数器类状态合约，拆分为“读取旧状态”和“验证新状态”两个阶段 | 编译状态合约练习并查看输出 | 分别调试读取旧状态和验证新状态的函数，观察数据如何在函数间传递 | 能解释状态合约如何证明旧状态可信，并如何验证新输出中的状态符合预期 |
| 第 12 天 | 测试、错误排查与部署调用认知 | 冒烟测试、成功路径、拒绝路径、边界值、常见编译与运行错误、部署数据流、调用数据流、交易构造、签名、广播 | 测试文档、调试文档、部署与调用说明、交易构造资料 | 为练习合约准备正常、失败、边界三类输入；梳理 P2PKH 与状态合约的部署/调用数据流 | 编译成功路径和失败路径练习，生成调试信息，了解交易构造、签名和广播工具的职责边界 | 对失败路径设置断点，观察验证指令触发终止时的执行位置；如果准备了交易数据文件，练习加载交易上下文和查看交易 | 能区分语法错误、类型错误、所有权错误、导入失败和运行时验证失败，并能说明合约编译、交易构造、签名和广播之间的职责边界 |
| 第 14 天 | 综合练习 | 需求拆解、合约编写、编译输出审查、调试、测试、错误排查、说明记录 | 复习前述全部主题 | 完成一个小型综合练习，例如“签名校验 + 计数状态推进”或“带路径参数的条件锁定合约” | 编译综合练习并查看输出 | 至少调试一条成功路径和一条拒绝路径；至少查看一次栈、回溯和字节码 | 能独立完成一个小型合约练习，并能解释从合约到锁定脚本、再到解锁参数和测试验证的完整链路 |

## 最终能力检查清单

| 能力项 | 达标标准 |
|---|---|
| 准备开发环境 | 能运行合约编译工具并查看版本或帮助信息 |
| 编写基础合约 | 能写出包含合约声明、公有函数、私有函数、类型声明和返回值的合约 |
| 理解 UTXO 与栈式虚拟机 | 能解释 UTXO、锁定脚本、解锁脚本、主栈、副栈和脚本执行顺序 |
| 使用编译工具 | 能编译合约源文件并生成结构化输出 |
| 阅读编译输出 | 能识别并解释元数据、结构体信息、ABI、函数列表、锁定脚本、解锁脚本 |
| 掌握所有权系统 | 能修复变量或字段被重复消耗导致的编译错误，能正确复制需要复用的数据 |
| 使用标准库 | 能导入和调用标准库函数，并能核对真实函数签名 |
| 编写 P2PKH 合约 | 能实现哈希校验和签名校验，并调试通过与失败两条路径 |
| 理解合约状态 | 能说明成员变量如何固化到脚本或状态数据中 |
| 理解状态合约 | 能解释父交易、当前交易、状态读取和状态递增校验 |
| 使用调试器 | 能使用断点、运行、继续、单步、跳过、退出函数、查看栈、回溯和查看字节码 |
| 编写测试 | 能准备成功路径、拒绝路径、边界条件，并用编译器和调试器验证 |
| 排查常见错误 | 能区分语法错误、类型错误、所有权错误、导入失败和运行时验证失败 |
| 完成综合练习 | 能交付练习合约、编译结果、测试记录、调试记录和简短说明 |

## 需进一步确认的能力边界

| 能力边界 | 说明 |
|---|---|
| 真实链上部署与广播 | 通常需要结合钱包、节点、SDK、交易构造工具和网络配置；学习初期可先理解流程，不必一开始完成真实广播 |
| 交易数据文件来源 | 调试器或测试工具需要的交易上下文通常由交易构造工具、测试框架或样例数据生成 |
| 构造函数工作流 | 不同合约语言对构造函数、成员变量初始化和部署参数的约定可能不同，学习时需以实际语言规范为准 |
| 脚本包装方式 | 不同链或工具可能采用不同脚本包装方式，完整部署流程需结合目标运行环境确认 |
