PTB Builder Handbook

A Beginner’s Guide to Move and Programmable Transaction Blocks

Foreword

This handbook is a short guide for those who are new to the Move language and Programmable Transaction Blocks (PTBs). Move is a language designed to safely manage digital assets on blockchains. By following this guide, you will write and run code, and experience token issuance and PTB construction firsthand. With just 2–3 hours of practice, you can directly experience the power of Move and PTBs.

Table of Contents

1. Introduction to Move
2. Environment Setup
   • Install Sui CLI (basic)
   • Install VS Code – Sui Extension
3. Quick Start
   • CLI Quick Start
   • VS Code – Sui Extension Quick Start
4. Objects and Resources
5. PTB Practice 🌟
6. Further Reading

1. Introduction to Move

💡 Key Terms Preview

• Move: An asset-centric smart contract language for blockchains
• Resource: A value that cannot be copied or deleted, only moved
• Module: The basic unit of Move code (contains functions and types)

What is Move?

• Move is a programming language designed to safely manage blockchain assets.
• It started in Facebook’s Libra project (2018) and is now used in Sui, Aptos, and other blockchains.
• The name comes from the action of “moving values instead of copying them”, reflecting its asset-centric model.

Core Values of Move

• Security: Prevents assets from being copied or deleted at the language level
• Expressiveness: Flexible design of asset-related logic
• Accessibility: Easy to use for both smart contracts and applications

Key Features of Move

• Resource Types: Digital assets cannot be copied/deleted, only moved
• Ability System: Strictly controls how values are created, stored, and transferred
• Module System: Supports code reuse and encapsulation
• PTB (Programmable Transaction Block): Batch multiple operations into a single transaction

Move on Sui

• Object-Centric Model: Assets are managed as objects
• Unique Object IDs: Each object has a globally unique identifier
• Parallel Execution: Transactions without conflicts can be executed simultaneously
• Entry Functions: Special entry points callable by anyone

2. Environment Setup

💡 Key Terms Preview

• Sui CLI: Basic tool for building, testing, and deploying Move packages
• VS Code Extension: GUI-based toolkit for development
• Workspace: Project unit managed by the VS Code Extension
• Explorer View: Project navigation/creation menu in VS Code

2.1 Install Sui CLI

• macOS / Linux / WSL:

brew install sui

• Windows:

choco install sui

Check installation:

sui --version

⚠️ Sui CLI is required to build and run Move code. Install it first before continuing.

2.2 Install VS Code – Sui Extension

The Sui Extension lets you compile, deploy, and test Move smart contracts, and also visually build and execute PTBs inside VS Code.

Key Features

• Compile & Deploy
• Upgrade Support (upgrade.toml)
• Object Explorer
• Package Explorer
• Built-in PTB Builder (drag-and-drop)

Installation

1. Open VS Code → Extensions (⇧⌘X / Ctrl+Shift+X)
2. Search for Sui Extension and install
3. Restart VS Code

⚠️ Requirement: Sui CLI must be installed first.

3. Quick Start

💡 Key Terms Preview

• Build: Compile Move code into modules
• Test: Run unit tests
• Deploy: Upload a package to the network
• Package Explorer: UI to view/call deployed modules and functions

3.1 CLI Quick Start

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

3.2 VS Code – Extension Quick Start

1. In Explorer View, right-click → New Move Project
2. Choose the Hello World template
3. Click the Sui Extension icon in the Activity Bar
4. In Workspace, select the hello_move package and run Build / Test / Deploy
5. After deployment, a new Package Card appears in the Package Explorer

💧 Get Testnet Tokens

To run tests, you need Testnet SUI. 👉 Claim from the official Faucet.

4. Objects and Resources

💡 Key Terms Preview

• Coin: Object that represents a token
• TreasuryCap: Object with mint/burn authority
• Entry Function: A function callable directly from outside

After learning Move basics, you can try out real coins and permission models. Use the Sui Extension template Sui Move Intro Course: Fungible Token (Managed) to quickly understand coin issuance and the TreasuryCap model.

📌 Using the Template (VS Code Sui Extension)

1. Right-click in Explorer → New Move Project
2. Select Sui Move Intro Course: Fungible Token (Managed)
3. In Sui Extension → Workspace, run Build/Test/Deploy

Key Code Snippets

Define Coin Type

public struct MANAGED has drop {}

Initialization

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

Only accounts holding the TreasuryCap can call mint/burn.

5. PTB Practice 🌟

5.1 Preparation

• Build & Deploy
• In Owner Objects Explorer, check that you own TreasuryCap<...::MANAGED>

5.2 Running in the Extension

1. After deployment, open Package Explorer

2. Select the mint function → enter arguments (treasury_cap, amount, recipient)

3. Run → new Coin<MANAGED> is created

   

5.3 Running in PTB Builder

1. Open PTB Builder

2. Add a node: moveCall → managed::mint

3. Enter arguments:

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

4. Execute → check Transaction Digest

   

⚡️ PTB Builder automatically generates TypeScript code for executed configurations. Use Export/Copy to integrate into your project.

5.4 Using ptb.wal.app

• Web-based PTB Builder: ptb.wal.app

• Features:

  • Build and execute PTBs
  • Enter tx digest → visualize transactions
  • Export PTBs as files
  • Convert PTBs into TypeScript code

  

6. Further Reading

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