PTB Builder Handbook

A Beginner’s Guide to Move and Programmable Transaction Blocks

서문 (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(프로그래머블 트랜잭션 블록): 여러 작업을 한 번에 묶어 실행 가능

Sui에서의 Move

오브젝트 중심 모델: 자산을 오브젝트 단위로 관리
고유한 Object ID: 모든 오브젝트는 전역에서 유일
병렬 실행: 충돌 없는 트랜잭션은 동시에 실행 가능
Entry 함수 (Entry function): 누구나 호출할 수 있는 특별한 진입점 함수

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 스마트 컨트랙트를 컴파일, 배포, 테스트하고, Programmable Transaction Blocks를 시각적으로 구성하고 실행할 수 있는 확장 도구입니다.

주요 기능

컴파일 & 배포
업그레이드 지원 (upgrade.toml 기반)
오브젝트 탐색기
패키지 탐색기
PTB Builder 내장 (드래그 앤 드롭)

설치 방법

VS Code 열기 → Extensions (⇧⌘X / Ctrl+Shift+X)
Sui Extension 검색 후 설치
설치 후 재시작

⚠️ 필수 조건: Sui CLI가 먼저 설치되어 있어야 합니다.

3. 빠른 시작

💡 핵심 용어 미리보기

Build: Move 코드를 컴파일해 모듈 생성
Test: Move 단위 테스트 실행
Deploy: 네트워크에 패키지 업로드
Package Explorer: 배포된 모듈과 함수를 확인/호출하는 UI

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 함수 (Entry function): 외부에서 직접 호출 가능한 함수

Move 기본 문법을 익힌 뒤, 실제 코인과 권한 모델을 직접 체험합니다. Sui Extension 템플릿 Sui Move Intro Course: Fungible Token (Managed) 을 활용해, 배포자가 발행(mint)·소각(burn)할 수 있는 코인과 TreasuryCap 권한 모델을 빠르게 이해합니다.

📌 템플릿 가져오기 (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);
}

mint/burn는 TreasuryCap 보유자만 호출할 수 있습니다.

5. PTB 실습 🌟

5.1 준비

Build & Deploy
Owner Objects Explorer에서 TreasuryCap<...::MANAGED> 확인

5.2 익스텐션에서 실행

Deploy 후 → 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를 파일로 내보내기(export)
- PTB를 TypeScript 코드로 변환

PTB Builder Handbook ​

서문 (Foreword) ​

목차 (Table of Contents) ​

1. Move 소개 ​

💡 핵심 용어 미리보기 ​

Move란? ​

Move의 핵심 가치 ​

Move의 주요 특징 ​

Sui에서의 Move ​

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 익스텐션에서 실행 ​

5.3 PTB Builder에서 실행 ​

5.4 ptb.wal.app 활용 ​

6. 참고 자료 ​

PTB Builder Handbook

서문 (Foreword)

목차 (Table of Contents)

1. Move 소개

💡 핵심 용어 미리보기

Move란?

Move의 핵심 가치

Move의 주요 특징

Sui에서의 Move

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 익스텐션에서 실행

5.3 PTB Builder에서 실행

5.4 ptb.wal.app 활용

6. 참고 자료