Sui Client PTB CLI
client ptb 명령어를 사용하면 CLI 또는 bash 스크립트를 통해 programmerble transaction block(PTB)에서 실행할 transaction을 지정할 수 있다.
이 문서의 예제는 bash 셸 환경에서 테스트되었다. 사용하는 셸이 입력 값을 해석하는 방식에 따라 결과가 다를 수 있다(예: zsh는 대괄호로 전달되는 값에 따옴표:"[]"를 사용해야 하는 반면; bash는 따옴표 없이도 값을 사용할 수 있다). Windows에서는 전달되는 인수에 따옴표를 더 추가해야하는 경우도 있다(예: --assign "forge @<FORGE-ID>" ).
Commands
다음 목록은 sui client ptb 명령에 사용할 수 있는 모든 인수를 나열한 것이다. 자세한 도움말을 보려면 --help 옵션을 사용한다. 여기에는 이 명령 사용 방법에 대한 예제가 포함되어 있다.
Build, preview, and execute programmable transaction blocks. Depending on your shell, you might have to use quotes around arrays or other passed values. Use --help to see examples for how to use the core functionality of this
command.
Usage: sui client ptb [OPTIONS]
Options:
--assign <NAME> <VALUE>
Assign a value to a variable name to use later in the PTB.
If only a name is supplied, the result of the last transaction is bound to that name.
If a name and value are supplied, then the name is bound to that value.
Examples:
--assign MYVAR 100
--assign X [100,5000]
--split-coins gas [1000, 5000, 75000]
--assign new_coins # bound new_coins to the result of previous transaction
--dry-run
Perform a dry run of the PTB instead of executing it.
--gas-coin <ID>
The object ID of the gas coin to use. If not specified, it will try to use the first gas coin that it finds that has at least the requested gas-budget balance.
--gas-budget <MIST>
An optional gas budget for this PTB (in MIST). If gas budget is not provided, the tool will first perform a dry run to estimate the gas cost, and then it will execute the transaction. Please note that this incurs a small
cost in performance due to the additional dry run call.
--make-move-vec <TYPE> <[VALUES]>
Given n-values of the same type, it constructs a vector. For non objects or an empty vector, the type tag must be specified.
Examples:
--make-move-vec <u64> []
--make-move-vec <u64> [1, 2, 3, 4]
--make-move-vec <std::option::Option<u64>> [none,none]
--make-move-vec <sui::coin::Coin<sui::sui::SUI>> [gas]
--merge-coins <INTO_COIN> <[COIN OBJECTS]>
Merge N coins into the provided coin.
Examples:
--merge-coins @coin_object_id [@coin_obj_id1, @coin_obj_id2]
--move-call <PACKAGE::MODULE::FUNCTION> <TYPE_ARGS> <FUNCTION_ARGS>
Make a move call to a function.
Examples:
--move-call std::option::is_none <u64> none
--assign a none
--move-call std::option::is_none <u64> a
--split-coins <COIN> <[AMOUNT]>
Split the coin into N coins as per the given array of amounts.
Examples:
--split-coins gas [1000, 5000, 75000]
--assign new_coins # bounds the result of split-coins command to variable new_coins
--split-coins @coin_object_id [100]
--transfer-objects <[OBJECTS]> <TO>
Transfer objects to the specified address.
Examples:
--transfer-objects [obj1, obj2, obj3] @address
--split-coins gas [1000, 5000, 75000]
--assign new_coins # bound new_coins to result of split-coins to use next
--transfer-objects [new_coins.0, new_coins.1, new_coins.2] @to_address
--publish <MOVE_PACKAGE_PATH>
Publish the Move package. It takes as input the folder where the package exists.
Examples:
--move-call sui::tx_context::sender
--assign sender
--publish "."
--assign upgrade_cap
--transfer-objects "[upgrade_cap]" sender
--upgrade <MOVE_PACKAGE_PATH>
Upgrade the move package. It takes as input the folder where the package exists.
--preview
Preview the list of PTB transactions instead of executing them.
--serialize-unsigned-transaction
Instead of executing the transaction, serialize the bcs bytes of the unsigned transaction data using base64 encoding.
--serialize-signed-transaction
Instead of executing the transaction, serialize the bcs bytes of the signed transaction data using base64 encoding.
--summary
Show only a short summary (digest, execution status, gas cost). Do not use this flag when you need all the transaction data and the execution effects.
--warn-shadows
Enable shadow warning when the same variable name is declared multiple times. Off by default.
--json
Return command outputs in json format.
-h, --help
Print help (see a summary with '-h')
Design philosophy and concepts
CLI PTB 지원의 핵심 철학은 사용자가 명령줄에서 PTB를 구성하고 실행할 수 있도록 하는 것이다. Bash 스크립트를 사용하여 명령줄에서와 마찬가지로 PTB를 구성하고 실행할 수 있으므로 다양한 작업을 자동화하는 데 뛰어난 유연성을 제공한다.
기존의 traditional PTB 관련 개념을 활용하는 것 외에도, 이 명령에 몇 가지 새롭고 중요한 개념을 소개한다.
다음 예제들은 모두 bash 셸 환경에서 테스트되었으며, 사용하는 셸이 입력값을 해석하는 방식에 따라 결과가 다를 수 있다(예: zsh는 값을 괄호로 묶어 전달해야 한다: "[]"; bash는 따옴표 없이도 값을 허용한다).
Types
간혹 CLI PTB에서는 값이나 변수 유형을 지정하는 경우가 있다. 예를 들어, 다음 예제에서는 0x1::option::is_none 함수를 호출할 때 <u64> 유형을 제공해야 한다.
$ sui client ptb \
--assign my_variable none \
--move-call 0x1::option::is_none "<u64>" my_variable \
--gas-budget 50000000
여러 데이터 유형을 전달하려면 쉼표로 구분한다:
...
--move-call package::module::function "<u64,u8,u256>" \
...
Strings
CLI PTB는 문자열 리터럴을 입력으로 지원하며, 이러한 문자열은 vector<u8> , std::ascii::String 및 std::string::String 매개변수의 입력으로 사용할 수 있는 순수 값으로 인코딩된다. 다음 예제는 "Hello, world" 문자열을 $PKG 패키지(해당 패키지 ID는 환경 변수에 저장됨)의 함수 m::f 에 전달하는 transaction 블록을 미리 보여준다.
$ sui client ptb --move-call "$PKG::m::f" '"Hello, world"' --gas-budget 10000000 --preview
큰따옴표로 묶인 문자열 리터럴은 bash 와 같은 셸에서도 유효한 구문인 경우가 많으므로 명령줄에서 PTB를 입력할 때는 이전 예제처럼 큰따옴표가 그대로 해석되도록 전체 문자열을 작은따옴표로 묶어야 한다.
Addresses and Object IDs
You can pass literal addresses and objects IDs by prefixing them with '@'. This is needed to distinguish a hexadecimal value from an address in some situations.
For addresses that are in your local wallet, you can use their alias instead (passing them without '@', for example, --transfer-objects my_alias).
다음은 transfer-objects 와 gas-coin 에 대한 몇 가지 예시이다:
$ sui client ptb --transfer-objects "[ARRAY_OF_OBJECTS]" @0x02a212de6a9dfa3a69e22387acfbafbb1a9e591bd9d636e7895dcfc8de05f331 --gas-coin @0x00002819ee07a66e53800495ccf5eeade8a02054a2e0827546c70e4b226f0495
Vectors
CLI PTB는 입력으로 직렬화 가능한 타입의 벡터를 지원한다(모든 기본 타입, ID 및 Option 포함). 벡터는 대괄호 안에 쉼표로 구분된 값들의 목록으로 표현되며, 각 대괄호 앞에는 vector가 붙는다.
$ sui client ptb --move-call "$PKG::m::f" vector[1, 2, 3]
위 예시는 정수 값으로 이루어진 벡터를 나타낸다. 벡터의 유형에 따라 지원되는 모든 유형을 전달할 수 있다.
--move-call package::module::function vector[@0x1, @0x2, @0x3] # vector<address>
--move-call package::module::function vector[none, none] # vector<Option<T>>
--move-call package::module::function vector["1", "2", "3"] # vector<String>
Option
옵션은 none 또는 some(value) 로 표시된다. 값은 지원되는 모든 기본 유형, ID 또는 Option 일 수 있다.
$ sui client ptb --move-call "0x1::option::destroy_some" some(2)
none의 경우 none 키워드를 사용한다. some이 필요한 경우 some 키워드 뒤에 값을 입력한다.
$ sui client ptb --move-call "0x1::option::destroy_none" none
Addresses
Assign
변수에 값을 할당하려면 --assign 인수를 사용한다. 사용 방법은 두 가지가 있다.
- 변수에 값을 할당
- 이전 명령의 결과를 변수에 할당
변수에 값을 할당하는 첫 번째 경우를 보자. 어떤 변수의 값이 none 인지 확인하고자 한다. Move 표준 라이브러리의 0x1::option::is_none 함수를 호출하고 변수 이름을 전달한다:
$ sui client ptb \
--assign my_variable none \
--move-call 0x1::option::is_none "<u64>" my_variable \
--gas-budget 50000000
CLI PTB는 sui , std , deepbook 과 같은 일반 패키지에 대해 이름 확인을 사용하므로, 주소 대신 해당 패키지를 직접 사용할 수 있다: 0x2 , 0x1 또는 0xdee9
두 번째 경우, 이전 명령의 결과가 출력되면 해당 결과를 변수에 저장하여 나중에 사용할 수 있다. 예를 들어, split-coins 명령을 사용하여 1000 MIST 상당의 새 코인을 생성한다. 이렇게 생성한 후, 새 코인을 다른 주소로 전송시도를 한다. 이때 --assign 인수를 사용하지 않으면 해당 코인 object를 참조할 방법이 없으므로 CLI에 전송 명령을 내릴 수 없다.
$ sui client ptb \
--split-coins gas "[1000]" \
--assign coin \
--transfer-objects "[coin]" @recipient_address \
--gas-budget 50000000
복잡한 PTB를 구축하는 경우, 실행 대신 --preview 플래그를 사용하여 PTB transaction 목록을 표시할 수 있다.
Examples
다음 예제는 client ptb 명령어를 사용하는 방법을 보여준다.
PTB 가 실행되면 출력에는 모든 관련 정보(transaction 데이터, 가스 비용, 효과, object 변경 사항 등)가 포함된다. 모든 데이터가 필요하지 않은 경우 --summary를 사용하여 간략한 요약을 얻을 수 있다. 복잡한 PTB의 경우 실행 대신 --preview를 사용하여 PTB transaction 목록을 표시할 수 있다.
Move call
Move 호출을 실행해야 할 때는 --move-call transaction을 사용하여 패키지 내의 특정 함수를 호출한다. CLI PTB는 sui , std , deepbook 과 같은 일반적인 패키지에 대한 이름 확인을 지원하므로 함수 이름을 전달할 때 0x1::option::is_none 과 std::option::is_none 모두 사용할 수 있다.
--assign A none
--move-call std::option::is_none "<u64>" A
특정 패키지의 특정 함수를 호출하려면 다음과 같은 호출 방식을 사용할 수 있다:
--move-call PACKAGE_ADDR::MODULE::FUNCTION "<TYPE>" FUNC_ARG1 FUNC_ARG2 ...
Publish
Sui를 사용할 때 가장 중요한 명령어 중 하나는 패키지 게시이다. CLI에는 독립적인 publish 명령어가 있지만, PTBs에서도 패키지 게시 및 업그레이드를 지원한다. 주요 차이점은 sui client ptb를 사용할 경우 패키지 생성 시 반환되는 UpgradeCap object를 명시적으로 전달하거나 make_immutable 호출을 통해 소멸시켜야 한다. 다음은 sui client ptb 명령어를 사용하여 Move 프로젝트를 체인에 게시하는 예시이다. 이 예는 sui::tx_context::sender를 호출하여 발신자를 획득하고 해당 호출 결과를 sender 변수에 할당한 다음 게시 명령어를 호출한다. publish 의 결과는 upgrade_cap 변수에 바인딩되고, 이 object는 발신자로 전달된다.
$ sui client ptb \
--move-call sui::tx_context::sender \
--assign sender \
--publish "." \
--assign upgrade_cap \
--transfer-objects "[upgrade_cap]" sender \
--gas-budget 100000000
Split, destroy, and merge coins
다음 예제는 가스 코인을 여러 개의 코인으로 분할하고, move 호출을 통해 새 코인 중 하나 이상을 소멸시킨 다음, 소멸되지 않은 코인들을 다시 가스 코인으로 병합하는 방법을 보여준다. 또한 프레임워크 이름 해석(예: 0x2::coin 대신 sui::coin 사용)과 . 구문을 사용하여 배열의 여러 값을 참조하는 방법도 보여준다.
# Split off from gas
--split-coins gas "[0,1,2,3]"
--assign coins
--move-call sui::coin::destroy_zero<sui::sui::SUI> coins.0
# Can further split a split coin (and through variable bindings/result accesses)
--split-coins coins.1 "[0,0]"
--assign zcoins
# Destroy both new coins
--move-call sui::coin::destroy_zero<sui::sui::SUI> zcoins.0
--move-call sui::coin::destroy_zero<sui::sui::SUI> zcoins.1
# Can merge the split coins back
--merge-coins gas "[coins.1, coins.2, coins.3]"
--gas-budget 10000000
Transfer objects
이 예시는 가스를 통해 세 개의 새로운 코인을 생성하고 이를 다른 주소로 전송한다.
--assign to_address @0x02a212de6a9dfa3a69e22387acfbafbb1a9e591bd9d636e7895dcfc8de05f331 \
--split-coins gas "[1,2,3]" \
--assign s \
--transfer-objects "[s.0, s.1, s.2]" to_address \
--gas-budget 10000000
주소 대신 별칭(‘@’ 없이)을 전달할 수도 있다.
Reserved words
다음 단어들은 변수 이름으로 사용할 수 없다.
addressboolvectorsomenonegasu8u16u32u64u128u256
JSON output
Sui CLI의 인간 친화적인 기본 출력 형식 대신 JSON 형식으로 응답을 표시하려면 명령어에 --json 플래그를 추가한다. 이는 데이터 세트가 매우 큰 경우, 특히 작은 화면에서 결과가 제대로 표시되지 않을 때 유용하다. 이러한 경우에 --json 플래그를 사용하면 편리하다.