PTB Builder Handbook

A Beginner’s Guide to Move and Programmable Transaction Blocks

서문 (Foreword)

이 책은 Move 언어와 PTB를 처음 배우는 분들을 위한 짧은 안내서입니다. Move는 블록체인에서 자산을 안전하게 다루기 위해 설계된 언어입니다. 여러분은 이 책을 따라가면서, 코드를 배우고 실행해보며, 마침내 간단한 지갑을 만들어보게 될 것입니다. 단 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 함수: 누구나 호출할 수 있는 특별한 진입점 함수.

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를 시각적으로 구성하고 실행할 수 있는 확장 도구입니다.

주요 기능

컴파일 & 배포: Move.toml이 있는 디렉토리에서 바로 실행
업그레이드 지원: upgrade.toml이 있으면 기존 패키지를 갱신
오브젝트 탐색기: 계정/오브젝트 상태를 불러와 확인 가능
패키지 탐색기: 배포된 스마트 컨트랙트 함수 호출/테스트
PTB Builder 내장: 드래그 앤 드롭으로 트랜잭션 블록 구성

설치 방법

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

⚠️ 필수 조건: Sui CLI가 먼저 설치되어 있어야 합니다. (CLI로 빌드/실행 처리)

3. 빠른 시작

💡 핵심 용어 미리보기

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

3.1 CLI 빠른 시작

새 프로젝트 생성

bash

sui move new hello_move
cd hello_move

빌드 & 테스트

bash

sui move build
sui move test

3.2 VS Code - Extension 빠른 시작

Explorer 뷰에서 원하는 폴더 우클릭 → New Move Project 선택 📸 스크린샷: Explorer에서 우클릭 메뉴에 New Move Project 표시
팝업에서 Hello World 템플릿 선택 📸 스크린샷: 템플릿 팝업에서 Hello World 강조
Activity Bar → Sui Extension 아이콘 클릭 📸 스크린샷: 사이드바에 Sui 아이콘 표시
Workspace 섹션에서 hello_move 패키지 선택 후 Build / Test / Deploy 실행 📸 스크린샷: Workspace에서 패키지와 실행 버튼 강조
배포 완료 시 Package Explorer에 새 패키지 카드 생성 📸 스크린샷: Package Explorer에 배포된 패키지 카드 표시
- 카드에는 배포된 스마트 컨트랙트 주소와 함수 목록 표시
- 함수를 직접 호출하여 실행 결과 확인 가능

4. 오브젝트와 리소스 맛보기

💡 핵심 용어 미리보기

오브젝트(Object): 블록체인에 저장되는 데이터 단위
UID: 오브젝트를 전역에서 구분하는 고유 식별자 (Unique ID)
Coin: 특정 토큰을 표현하는 오브젝트
TreasuryCap: 코인 발행/소각 권한을 가진 특별한 오브젝트
TxContext: 트랜잭션 실행 맥락(보낸이, 가스, 오브젝트 생성 등)을 담는 자동 인자
PTB (Programmable Transaction Block): 여러 작업을 하나로 묶어 원자적으로 실행하는 트랜잭션 묶음
Entry 함수: 외부에서 직접 호출 가능한 함수 (public entry fun ...)

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

예제 코드는 VS Code Sui Extension 템플릿의 fungible_tokens::managed 모듈입니다.

📌 템플릿 가져오기 (VS Code Sui Extension)

Explorer에서 원하는 폴더 우클릭 → New Move Project
템플릿 목록에서 Sui Move Intro Course: Fungible Token (Managed) 선택
생성된 워크스페이스를 Sui Extension → Workspace에서 선택 후 Build/Test/Deploy 진행

핵심 코드 발췌

1) 코인 타입 정의

move

public struct MANAGED has drop {}

코인 자체는 필드가 없는 빈 struct
has drop 어빌리티만 부여 → 단순 메타타입 역할

2) 초기화 (init)

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

배포 시 1회 실행
TreasuryCap<MANAGED> 오브젝트를 배포자 주소로 전송
이후 배포자만 mint/burn 가능

3) 민트 / 소각

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

민트: 권한 소유자가 지정 수량을 새로 발행하여 recipient에게 전송
소각: 권한 소유자가 기존 코인을 회수 후 제거

전체 코드는 VS Code Sui Extension 템플릿 **“Sui Move Intro Course: Fungible Token (Managed)”**에서 확인할 수 있습니다.

배포 후 오브젝트 확인 (개념 연결)

배포(Deploy) 완료 → init가 실행되어 TreasuryCap<MANAGED> 생성
Owner Objects Explorer에서 내 주소를 조회 → TreasuryCap<...::MANAGED> 보유 확인
이후 mint로 Coin<MANAGED>를 발행/전송, 필요 시 burn으로 소각

TypeScript 호출 예제 (트랜잭션 작성)

import { TransactionBlock } from '@mysten/sui.js/transactions';

// mint 호출
const tx = new TransactionBlock();
tx.moveCall({
  target: `${packageId}::managed::mint`,
  arguments: [
    tx.object(treasuryCapId), // &mut TreasuryCap<MANAGED>
    tx.pure(1000), // u64 → 10.00 단위 (소수점 2)
    tx.pure(recipient), // address
  ],
});

// burn 호출
const burnTx = new TransactionBlock();
burnTx.moveCall({
  target: `${packageId}::managed::burn`,
  arguments: [
    burnTx.object(treasuryCapId),  // &mut TreasuryCap<MANAGED>
    burnTx.object(coinId),         // Coin<MANAGED>
  ],
});

// 실행
await client.signAndExecuteTransactionBlock({ signer, transactionBlock: burnTx });

&mut TxContext는 런타임에서 자동 주입됩니다. TreasuryCap이 없는 계정이 mint/burn을 호출하면 실패합니다.

5. PTB 실습 🌟

여기서는 VS Code Sui Extension과 웹 프론트엔드 ptb.wal.app을 활용합니다.

5.1 Sui Extension UI 실습

Owner Objects Explorer에서 계정 소유 오브젝트 확인 📸 스크린샷: Explorer에 주소 입력 후 오브젝트 목록 표시
Package Explorer에서 mint / send 함수 호출 📸 스크린샷: 함수 호출 후 결과 확인
PTB Builder를 열어 mint → send를 시각적으로 연결 📸 스크린샷: PTB Builder 그래프에서 두 노드 연결

5.2 케이스 스터디: `fungible_tokens::managed` (MNG 코인)

모듈: fungible_tokens::managed
코인 타입: MANAGED (심볼: MNG, 소수점 2)
초기화: init(MANAGED, &mut TxContext) → 최초 배포 시 1회 실행, TreasuryCap<MANAGED> 발행 후 배포자에게 전송
민팅: mint(&mut TreasuryCap<MANAGED>, amount: u64, recipient: address, &mut TxContext)
소각: burn(&mut TreasuryCap<MANAGED>, Coin<MANAGED>)

배포 후 확인 절차

모듈을 Deploy하면, init가 실행되어 TreasuryCap<MANAGED>와 메타데이터가 생성됩니다.
Owner Objects Explorer에서 내 주소로 필터 → TreasuryCap<...::MANAGED> 오브젝트가 있는지 확인 📸 스크린샷: TreasuryCap<MANAGED> 오브젝트 표시

Package Explorer로 호출

mint: treasury_cap, amount, recipient 인자 전달 후 실행 → 새 Coin<MANAGED> 발행
burn: treasury_cap, coin 인자 전달 후 실행 → 해당 코인 소각

PTB Builder로 한 번에

예: mint(to=내 주소) → transferObjects(Coin<MANAGED>, 다른 주소) 체인 연결
여러 mint를 한 PTB에서 배치로 실행 가능 📸 스크린샷: PTB Builder에서 mint + transferObjects 연결

5.3 ptb.wal.app 활용

웹 기반 PTB Builder: ptb.wal.app 접속 후 사용 가능
주요 기능:
- PTB 직접 조립 및 실행
- tx digest 입력 → 이미 배포된 트랜잭션 불러와 시각화
- PTB를 파일로 내보내기(export) → VS Code Extension / ptb.wal.app에서 재사용 가능
- 내가 만든 PTB를 TypeScript 코드로 변환해 복사/활용 가능

📸 스크린샷: ptb.wal.app 실행 화면 (트랜잭션 불러오기, 익스포트, TS 코드 변환 UI)

6. 참고 자료 (Further Reading)

📖 The Move Book – Move 언어 공식 가이드
📘 Sui Smart Contracts Docs – Sui 스마트 컨트랙트 개발 문서
🧩 Mysten Labs Sui SDK (TypeScript) – Sui와 상호작용하는 TypeScript SDK
🛠 PTB Builder Online – PTB 시각적 구성 및 실행 도구
🧑‍💻 Sui Extension (VS Code Marketplace) – VS Code에서 Move/PTB 개발을 지원하는 확장

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. 오브젝트와 리소스 맛보기 ​

💡 핵심 용어 미리보기 ​

핵심 코드 발췌 ​

1) 코인 타입 정의 ​

2) 초기화 (init) ​

3) 민트 / 소각 ​

배포 후 오브젝트 확인 (개념 연결) ​

TypeScript 호출 예제 (트랜잭션 작성) ​

5. PTB 실습 🌟 ​

5.1 Sui Extension UI 실습 ​

5.2 케이스 스터디: fungible_tokens::managed (MNG 코인) ​

5.3 ptb.wal.app 활용 ​

6. 참고 자료 (Further Reading) ​

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. 오브젝트와 리소스 맛보기

💡 핵심 용어 미리보기

핵심 코드 발췌

1) 코인 타입 정의

2) 초기화 (init)

3) 민트 / 소각

배포 후 오브젝트 확인 (개념 연결)

TypeScript 호출 예제 (트랜잭션 작성)

5. PTB 실습 🌟

5.1 Sui Extension UI 실습

5.2 케이스 스터디: `fungible_tokens::managed` (MNG 코인)

5.3 ptb.wal.app 활용

6. 참고 자료 (Further Reading)