PTB Builder Handbook

Được viết cho người mới bắt đầu với Move và Programmable Transaction Blocks

Lời mở đầu (Foreword)

Cuốn sách này là một hướng dẫn ngắn gọn dành cho những ai mới bắt đầu học ngôn ngữ Move và PTB. Move được thiết kế để xử lý tài sản trên blockchain một cách an toàn. Khi làm theo cuốn sách này, bạn sẽ học cách viết và chạy code, và trực tiếp trải nghiệm phát hành token và xây dựng PTB. Chỉ cần 2~3 giờ, bạn sẽ cảm nhận được sức mạnh thực sự của Move và PTB.

Mục lục (Table of Contents)

1. Giới thiệu về Move
2. Cài đặt môi trường
   • Cài đặt Sui CLI (cơ bản)
   • Cài đặt VS Code - Sui Extension
3. Bắt đầu nhanh
   • Bắt đầu nhanh với CLI
   • Bắt đầu nhanh với VS Code - Sui Extension
4. Đối tượng và Tài nguyên
5. Thực hành PTB 🌟
6. Tài liệu tham khảo (Further Reading)

1. Giới thiệu về Move

💡 Thuật ngữ chính

• Move: Ngôn ngữ smart contract trên blockchain tập trung vào tài sản
• Resource (Tài nguyên): Giá trị không thể sao chép/xóa, chỉ có thể di chuyển
• Module (Mô-đun): Đơn vị cơ bản của code Move (bao gồm hàm và kiểu dữ liệu)

Move là gì?

• Move là ngôn ngữ lập trình được thiết kế để xử lý tài sản trên blockchain một cách an toàn.
• Bắt nguồn từ dự án Libra của Facebook (2018) và hiện được dùng trong Sui, Aptos và nhiều blockchain khác.
• Tên gọi xuất phát từ ngôn ngữ Move (nghĩa là "di chuyển mà không sao chép giá trị"), phản ánh bản chất của mô hình tài sản.

Giá trị cốt lõi của Move

• Bảo mật: Đảm bảo tài sản không bị sao chép hoặc xóa nhờ cơ chế ngôn ngữ
• Biểu đạt cao: Viết logic tài sản linh hoạt
• Trực quan: Dễ dàng tiếp cận cho cả smart contract và ứng dụng

Đặc điểm chính

• Resource types: Tài sản kỹ thuật số không thể sao chép/xóa, chỉ có thể di chuyển
• Ability system: Quản lý nghiêm ngặt việc tạo/lưu trữ/di chuyển giá trị
• Module system: Hỗ trợ tái sử dụng và đóng gói code
• PTB (Programmable Transaction Block): Gom nhiều thao tác thành một giao dịch duy nhất

Move trong Sui

• Mô hình dựa trên Object: Quản lý tài sản theo từng đối tượng
• Object ID duy nhất: Mỗi đối tượng có một định danh toàn cầu
• Thực thi song song: Các giao dịch không xung đột có thể chạy đồng thời
• Entry function: Hàm có thể gọi trực tiếp từ bên ngoài

2. Cài đặt môi trường

💡 Thuật ngữ chính

• Sui CLI: Công cụ cơ bản để build/test/deploy gói Move
• VS Code Extension: Bộ công cụ GUI hỗ trợ phát triển
• Workspace: Không gian dự án được quản lý bởi Extension
• Explorer view: Giao diện khám phá/tạo dự án trong VS Code

2.1 Cài đặt Sui CLI

• macOS / Linux / WSL:

brew install sui

• Windows:

choco install sui

Kiểm tra cài đặt:

sui --version

⚠️ Sui CLI là bắt buộc để build và chạy code Move.

2.2 Cài đặt VS Code - Sui Extension

Sui Extension cho phép bạn biên dịch, triển khai, kiểm thử smart contract Move và xây dựng/chạy PTB trực quan trong VS Code.

Chức năng chính

• Biên dịch & Triển khai
• Hỗ trợ nâng cấp (dựa trên upgrade.toml)
• Trình khám phá đối tượng
• Trình khám phá gói
• PTB Builder tích hợp (kéo thả)

Cách cài đặt

1. Mở VS Code → Extensions (⇧⌘X / Ctrl+Shift+X)
2. Tìm Sui Extension và cài đặt
3. Khởi động lại VS Code

⚠️ Điều kiện tiên quyết: Phải cài Sui CLI trước.

3. Bắt đầu nhanh

💡 Thuật ngữ chính

• Build: Biên dịch code Move để tạo mô-đun
• Test: Chạy unit test
• Deploy: Triển khai gói lên mạng
• Package Explorer: Giao diện quản lý mô-đun và hàm đã triển khai

3.1 Bắt đầu nhanh với CLI

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

3.2 Bắt đầu nhanh với VS Code Extension

1. Trong Explorer view, nhấp chuột phải thư mục → New Move Project
2. Chọn template Hello World
3. Nhấp vào biểu tượng Sui Extension trong Activity Bar
4. Trong Workspace, chọn gói hello_move và chạy Build / Test / Deploy
5. Sau khi deploy, một Package Card mới sẽ hiển thị trong Package Explorer

💧 Nhận token testnet

Để chạy thử nghiệm, bạn cần SUI testnet. 👉 Nhận tại Faucet chính thức.

4. Đối tượng và Tài nguyên

💡 Thuật ngữ chính

• Coin: Đối tượng biểu diễn token
• TreasuryCap: Đối tượng quyền phát hành/đốt
• Entry function: Hàm có thể gọi trực tiếp từ bên ngoài

Sau khi nắm ngữ pháp cơ bản, bạn sẽ trực tiếp trải nghiệm mô hình coin và quyền hạn. Template Sui Move Intro Course: Fungible Token (Managed) trong VS Code Extension sẽ giúp bạn hiểu cách phát hành (mint) và đốt (burn) token thông qua TreasuryCap.

📌 Tạo dự án từ template (VS Code Extension)

1. Trong Explorer, nhấp chuột phải → New Move Project
2. Chọn Sui Move Intro Course: Fungible Token (Managed)
3. Trong Workspace, chọn gói và chạy Build/Test/Deploy

Trích đoạn code chính

Định nghĩa Coin

public struct MANAGED has drop {}

Khởi tạo

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));
}

Mint / Burn

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);
}

Chỉ chủ sở hữu TreasuryCap mới có thể gọi mint/burn.

5. Thực hành PTB 🌟

5.1 Chuẩn bị

• Build & Deploy
• Kiểm tra TreasuryCap<...::MANAGED> trong Owner Objects Explorer

5.2 Chạy trong Extension

1. Sau khi deploy, mở Package Explorer

2. Chọn hàm mint → nhập tham số (treasury_cap, amount, recipient)

3. Chạy → tạo Coin<MANAGED> mới

   

5.3 Chạy trong PTB Builder

1. Mở PTB Builder

2. Thêm node: moveCall → managed::mint

3. Nhập tham số:

   • object(treasuryCapId)
   • pure.u64(amount)
   • pure.address(recipient)

4. Chạy → xem Transaction Digest

   

⚡️ PTB Builder tự động chuyển đổi cấu hình thành code TypeScript. Dùng Export/Copy để tái sử dụng trong phát triển.

5.4 Sử dụng ptb.wal.app

• PTB Builder trên web: ptb.wal.app

• Chức năng chính:

  • Xây dựng và chạy PTB
  • Dán tx digest → trực quan hóa giao dịch
  • Xuất PTB thành file
  • Chuyển đổi PTB thành code TypeScript

  

6. Tài liệu tham khảo

• 📖 The Move Book
• 🛠 PTB Builder Online
• 🧑‍💻 Sui Extension (VS Code Marketplace)