sui-client-ptb

Call a Move function from a package and module

$ sui client ptb --move-call p::m::f "<[type]>" args

$ sui client ptb --make-move-vec "<u64>" "[1000,2000]"

$ sui client ptb --split-coins gas "[1000]" --assign new_coins --transfer-objects "[new_coins]" @[address]

$ sui client ptb --transfer-objects "[[object_id]]" @[address]

$ sui client ptb --move-call sui::tx_context::sender --assign sender --publish "." --assign upgrade_cap --transfer-objects "[upgrade_cap]" sender

sui-client-ptb <SUBCOMMAND> [OPTIONS]

SUBCOMMANDS
    The specific action to perform related to Programmable Transaction Blocks. Common PTB-related subcommands typically include:

build: Used to construct a PTB from a high-level plan or a sequence of commands, which can then be serialized.
execute: Submits a previously built (and potentially signed) PTB to the Sui network for execution.
dry-run: Simulates the execution of a PTB without committing it to the network. This provides an estimate of gas costs and potential outcomes, useful for debugging.
sign: Generates a digital signature for a transaction digest or a serialized PTB, often required before submission to the network.

--gas-budget amount
    Sets the maximum gas budget (in SUI units) that can be spent on the transaction. The transaction will fail if its actual gas consumption exceeds this amount.

--gas-payment object_id
    Specifies the object ID of a SUI coin to be used as payment for gas fees. If omitted, the client will automatically select a suitable SUI coin from the active address's wallet.

--json
    Outputs the command's result in a structured JSON format, making it easier for scripts and other programs to parse the output.

--rpc url
    Specifies the URL of the Sui RPC (Remote Procedure Call) endpoint to connect to. This overrides the default or configured RPC URL.

--ws url
    Specifies the URL of the Sui WebSocket endpoint, typically used for real-time subscription services. This overrides the default or configured WS URL.

--sender address
    Defines the sender address for the transaction. If not provided, the command defaults to the active address configured in the Sui client's configuration file.

--profile name
    Selects a specific profile from the Sui client configuration. Profiles can contain different RPC URLs, active addresses, and keypairs.

The sui-client-ptb command-line utility provides a specialized interface for interacting with the Sui blockchain network, with a primary focus on Programmable Transaction Blocks (PTBs). PTBs are a core feature of Sui, enabling users to bundle multiple operations (e.g., asset transfers, object mutations, contract function calls) into a single, atomic, and deterministic transaction. This command empowers developers and advanced users to construct, simulate, sign, and execute complex transaction sequences, leveraging Sui's unique Move object model and efficient gas mechanics. It is an essential tool for building sophisticated decentralized applications, automating blockchain interactions, and managing Sui assets with granular control over transaction logic.

The sui-client-ptb command is an application-specific utility of the Sui blockchain ecosystem and is not a standard Linux system command. It requires a connection to a running Sui network (e.g., local, devnet, testnet, or mainnet). Effective use of this command demands familiarity with Sui's object model, the Move programming language, and the intricate structure of Programmable Transaction Blocks. The exact set of available subcommands and options may vary based on the specific version and build of the Sui client software.

PTBs on Sui are a sequence of commands that are executed atomically and deterministically. They allow for highly intricate logic to be performed in a single transaction, encompassing actions like transferring objects, calling arbitrary Move functions, creating new objects, and manipulating existing ones. This design enables highly expressive and efficient interactions with the Sui blockchain, significantly simplifying the development of complex decentralized applications by reducing the need for multiple, independent transactions.

All operations on the Sui network consume 'gas,' which is paid in SUI tokens. PTBs enable precise gas budgeting, allowing users to set a maximum limit for transaction costs. It is crucial for users to ensure their account has sufficient SUI to cover the estimated gas fees. The dry-run subcommand is an invaluable tool for estimating the gas consumption of a PTB before its actual execution, helping to prevent failed transactions due to insufficient funds.

Programmable Transaction Blocks (PTBs) were introduced as a foundational and differentiating feature of the Sui blockchain early in its development. They represent Sui's innovative approach to achieving atomic, composable transactions, offering developers unprecedented flexibility in defining complex interactions. The sui-client-ptb (or its integrated functionality within the broader sui client command) was developed to provide a direct command-line interface for interacting with and leveraging this powerful capability, evolving continuously alongside the Sui network itself.

sui client(1), sui node(1), move build(1)