PTB Builder Handbook

初学者的 Move 与可编程交易块 (PTB) 指南

前言 (Foreword)

本书是为刚开始学习 Move 语言和 PTB 的读者准备的简明指南。Move 是一种为安全处理区块链资产而设计的编程语言。通过本书，你将学习并运行代码，亲身体验代币发行与 PTB 构建。只需花费 2~3 小时，就能直接感受到 Move 和 PTB 的强大之处。

目录 (Table of Contents)

Move 简介
环境配置
- 安装 Sui CLI (基础)
- 安装 VS Code - Sui Extension
快速开始
- CLI 快速开始
- VS Code - Sui Extension 快速开始
对象与资源
PTB 实践 🌟
参考资料 (Further Reading)

1. Move 简介

💡 关键术语预览

Move：以资产为中心的区块链智能合约语言
资源 (Resource)：无法复制/删除，只能转移的值
模块 (Module)：Move 代码的基本单元（包含函数和类型）

什么是 Move？

Move 是为安全处理区块链资产而设计的编程语言。
起源于 Facebook 的 Libra 项目（2018），目前被 Sui、Aptos 等多条区块链采用。
名称源自 “值不复制，只移动 (move)” 的操作，体现了资产模型的核心。

Move 的核心价值

安全性：从语言层面保证资产不可复制或删除。
表达力：灵活编写资产逻辑。
直观性：智能合约与应用开发均易于上手。

Move 的主要特性

资源类型：数字资产不可复制/删除，只能转移。
Ability（能力）系统：严格控制值的创建、存储与转移方式。
模块系统：支持代码复用与封装。
PTB（可编程交易块）：可一次性执行多个操作。

Move 在 Sui 中的应用

对象驱动模型：以对象为单位管理资产。
唯一 Object ID：每个对象在全局唯一。
并行执行：无冲突交易可并发执行。
Entry 函数（入口函数）：可供任何人调用的特殊入口函数。

2. 环境配置

💡 关键术语预览

Sui CLI：构建/测试/部署 Move 包的核心工具。
VS Code Extension：提供 GUI 的开发工具包。
Workspace：VS Code Extension 管理的项目单元。
Explorer 视图：VS Code 中的项目导航/创建菜单。

2.1 安装 Sui CLI（基础）

macOS / Linux / WSL：

bash

brew install sui

Windows：

powershell

choco install sui

检查安装：

bash

sui --version

⚠️ Sui CLI 是 构建与运行 Move 代码的必要工具。必须先安装 CLI，后续步骤才能正常运行。

2.2 安装 VS Code - Sui Extension

Sui Extension 让你可以在 VS Code 中 编译、部署、测试 Move 合约，并 可视化构建与执行 PTB。

主要功能

编译与部署
升级支持（基于 upgrade.toml）
对象浏览器
包浏览器
内置 PTB Builder（拖放式）

安装方法

打开 VS Code → Extensions (⇧⌘X / Ctrl+Shift+X)
搜索 Sui Extension 并安装
安装完成后重启

⚠️ 前提条件：必须先安装 Sui CLI。

3. 快速开始

💡 关键术语预览

Build：编译 Move 代码生成模块
Test：运行 Move 单元测试
Deploy：将包上传到网络
Package Explorer：查看/调用已部署模块与函数的界面

3.1 CLI 快速开始

bash

sui move new hello_move
cd hello_move
sui move build
sui move test

3.2 VS Code - Extension 快速开始

在 Explorer 视图中右键目标文件夹 → 选择 New Move Project
在弹窗选择 Hello World 模板
点击 Activity Bar → Sui Extension 图标
在 Workspace 中选择 hello_move 包并执行 Build / Test / Deploy
部署完成后，Package Explorer 中会出现新的 包卡片

💧 获取测试网代币

运行示例需要 测试网 SUI。 👉 前往官方 Faucet 领取。

4. 对象与资源入门

💡 关键术语预览

Coin：表示代币的对象
TreasuryCap：具有发行/销毁权限的对象
Entry 函数（入口函数）：可从外部直接调用的函数

在学习完基础语法后，通过模板 Sui Move Intro Course: Fungible Token (Managed) 来 直接体验代币与权限模型，理解如何使用 TreasuryCap 进行发行（mint）与销毁（burn）。

📌 导入模板（VS Code Sui Extension）

在 Explorer 中右键文件夹 → New Move Project
模板列表选择 Sui Move Intro Course: Fungible Token (Managed)
在 Sui Extension → Workspace 中选择并执行 Build/Test/Deploy

核心代码节选

定义代币类型

move

public struct MANAGED has drop {}

初始化

move

fun init(witness: MANAGED, ctx: &mut TxContext) {
    let (treasury_cap, metadata) = sui::coin::create_currency<MANAGED>(
        witness, 2, b"MANAGED", b"MNG", b"", std::option::none(), ctx
    );
    sui::transfer::public_freeze_object(metadata);
    sui::transfer::public_transfer(treasury_cap, sui::tx_context::sender(ctx));
}

铸造 / 销毁

move

public fun mint(
    treasury_cap: &mut TreasuryCap<MANAGED>,
    amount: u64,
    recipient: address,
    ctx: &mut TxContext,
) {
    treasury_cap.mint_and_transfer(amount, recipient, ctx)
}
public fun burn(treasury_cap: &mut TreasuryCap<MANAGED>, coin: Coin<MANAGED>) {
    treasury_cap.burn(coin);
}

只有持有 TreasuryCap 的账户才能调用 mint / burn。

5. PTB 实践 🌟

5.1 准备

Build & Deploy
在 Owner Objects Explorer 中确认 TreasuryCap<...::MANAGED>

5.2 在 Extension 中执行

部署完成后 → 打开 Package Explorer
选择 mint 函数 → 输入参数（treasury_cap, amount, recipient）
执行 → 生成新的 Coin<MANAGED>

5.3 在 PTB Builder 中执行

打开 PTB Builder
添加节点：moveCall → managed::mint
输入参数：
- object(treasuryCapId)
- pure.u64(amount)
- pure.address(recipient)
执行 → 查看 Transaction Digest

⚡️ PTB Builder 会将执行的配置 转换为 TypeScript 代码。使用 Export/Copy 菜单导出并应用于你的开发代码。

5.4 使用 ptb.wal.app

网页版 PTB Builder：ptb.wal.app
主要功能：
- 构建与执行 PTB
- 输入 tx digest → 可视化已有交易
- 导出 PTB 文件
- 将 PTB 转换为 TypeScript 代码

PTB Builder Handbook ​

前言 (Foreword) ​

目录 (Table of Contents) ​

1. Move 简介 ​

💡 关键术语预览 ​

什么是 Move？ ​

Move 的核心价值 ​

Move 的主要特性 ​

Move 在 Sui 中的应用 ​

2. 环境配置 ​

💡 关键术语预览 ​

2.1 安装 Sui CLI（基础） ​

2.2 安装 VS Code - Sui Extension ​

主要功能 ​

安装方法 ​

3. 快速开始 ​

💡 关键术语预览 ​

3.1 CLI 快速开始 ​

3.2 VS Code - Extension 快速开始 ​

💧 获取测试网代币 ​

4. 对象与资源入门 ​

💡 关键术语预览 ​

核心代码节选 ​

定义代币类型 ​

初始化 ​

铸造 / 销毁 ​

5. PTB 实践 🌟 ​

5.1 准备 ​

5.2 在 Extension 中执行 ​

5.3 在 PTB Builder 中执行 ​

5.4 使用 ptb.wal.app ​

6. 参考资料 ​

PTB Builder Handbook

前言 (Foreword)

目录 (Table of Contents)

1. Move 简介

💡 关键术语预览

什么是 Move？

Move 的核心价值

Move 的主要特性

Move 在 Sui 中的应用

2. 环境配置

💡 关键术语预览

2.1 安装 Sui CLI（基础）

2.2 安装 VS Code - Sui Extension

主要功能

安装方法

3. 快速开始

💡 关键术语预览

3.1 CLI 快速开始

3.2 VS Code - Extension 快速开始

💧 获取测试网代币

4. 对象与资源入门

💡 关键术语预览

核心代码节选

定义代币类型

初始化

铸造 / 销毁

5. PTB 实践 🌟

5.1 准备

5.2 在 Extension 中执行

5.3 在 PTB Builder 中执行

5.4 使用 ptb.wal.app

6. 参考资料