[cli] Add CLI PTB support (#16207)

## Description This PR adds support for writing and executing programmable transaction blocks from the CLI. In a nutshell, a new command is introduced: `sui client ptb`, where the user can pass in different arguments that correspond either to transactions or other flags (e.g., preview to list the transactions in the PTB without executing the PTB). ## Test Plan Snapshot testing, unit tests, etc. ``` cd crates/sui && cargo nextest run ``` --- If your changes are not user-facing and do not break anything, you can skip the following section. Otherwise, please briefly describe what has changed under the Release Notes section. ### Type of Change (Check all that apply) - [ ] protocol change - [x] user-visible impact - [ ] breaking change for a client SDKs - [ ] breaking change for FNs (FN binary must upgrade) - [ ] breaking change for validators or node operators (must upgrade binaries) - [ ] breaking change for on-chain data layout - [ ] necessitate either a data wipe or data migration ### Release notes Added support for writing and executing programmable transaction blocks from the CLI. In a nutshell, a new command is introduced: `sui client ptb`, where the user can pass in different arguments that correspond either to transactions or other flags (e.g., preview to list the transactions in the PTB without executing the PTB). Use the `sui client ptb --help` for the help menu that explains all the commands and shows some usage examples . --------- Co-authored-by: Timothy Zakian <[email protected]>
MystenLabs · Feb 26, 2024 · ac0d032 · ac0d032
1 parent dd7ab45
commit ac0d032
Show file tree

Hide file tree

Showing 133 changed files with 12,330 additions and 332 deletions.
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -358,6 +358,7 @@ leb128 = "0.2.5"
 lru = "0.10"
 markdown-gen = "1.2.1"
 match_opt = "0.1.2"
+miette = {version = "7", features = ["fancy"] }
 mime = "0.3"
 mockall = "0.11.4"
 moka = { version = "0.12", default-features = false, features = ["sync", "atomic64"] }
@@ -518,6 +519,8 @@ x509-parser = "0.14.0"
 zstd = "0.12.3"
 zeroize = "1.6.0"
 versions = "4.1.0"
+linked-hash-map = "0.5.6"
+shlex = "1.3.0"
 
 # Move dependencies
 move-binary-format = { path = "external-crates/move/crates/move-binary-format" }

diff --git a/crates/sui-json/src/lib.rs b/crates/sui-json/src/lib.rs
@@ -542,7 +542,7 @@ fn check_valid_homogeneous_rec(curr_q: &mut VecDeque<&JsonValue>) -> Result<(),
     check_valid_homogeneous_rec(&mut next_q)
 }
 
-fn is_primitive_type_tag(t: &TypeTag) -> bool {
+pub fn is_primitive_type_tag(t: &TypeTag) -> bool {
     match t {
         TypeTag::Bool
         | TypeTag::U8

diff --git a/crates/sui-sdk/src/wallet_context.rs b/crates/sui-sdk/src/wallet_context.rs
@@ -188,7 +188,7 @@ impl WalletContext {
             }
         }
         Err(anyhow!(
-            "No non-argument gas objects found with value >= budget {budget}"
+            "No non-argument gas objects found for this address with value >= budget {budget}. Run sui client gas to check for gas objects."
         ))
     }
 

diff --git a/crates/sui-transaction-builder/src/lib.rs b/crates/sui-transaction-builder/src/lib.rs
@@ -771,7 +771,7 @@ impl TransactionBuilder {
     }
 
     // TODO: we should add retrial to reduce the transaction building error rate
-    async fn get_object_ref(&self, object_id: ObjectID) -> anyhow::Result<ObjectRef> {
+    pub async fn get_object_ref(&self, object_id: ObjectID) -> anyhow::Result<ObjectRef> {
         self.get_object_ref_and_type(object_id)
             .await
             .map(|(oref, _)| oref)

diff --git a/crates/sui-types/src/lib.rs b/crates/sui-types/src/lib.rs
@@ -226,7 +226,7 @@ pub fn parse_sui_type_tag(s: &str) -> anyhow::Result<TypeTag> {
 }
 
 /// Resolve well-known named addresses into numeric addresses.
-fn resolve_address(addr: &str) -> Option<AccountAddress> {
+pub fn resolve_address(addr: &str) -> Option<AccountAddress> {
     match addr {
         "deepbook" => Some(DEEPBOOK_ADDRESS),
         "std" => Some(MOVE_STDLIB_ADDRESS),

diff --git a/crates/sui/Cargo.toml b/crates/sui/Cargo.toml
@@ -34,6 +34,12 @@ num-bigint.workspace = true
 regex.workspace = true
 reqwest.workspace = true
 im.workspace = true
+async-recursion.workspace = true
+thiserror.workspace = true
+miette.workspace = true
+datatest-stable.workspace = true
+insta.workspace = true
+shlex.workspace = true
 
 sui-config.workspace = true
 sui-execution = { path = "../../sui-execution" }
@@ -51,6 +57,8 @@ sui-move-build.workspace = true
 sui-protocol-config.workspace = true
 shared-crypto.workspace = true
 sui-replay.workspace = true
+sui-transaction-builder.workspace = true
+move-binary-format.workspace = true
 
 fastcrypto.workspace = true
 fastcrypto-zkp.workspace = true
@@ -68,6 +76,7 @@ move-core-types.workspace = true
 move-package.workspace = true
 csv.workspace = true
 move-vm-profiler.workspace = true
+move-command-line-common.workspace = true
 
 [target.'cfg(not(target_env = "msvc"))'.dependencies]
 jemalloc-ctl.workspace = true
@@ -84,6 +93,9 @@ sui-simulator.workspace = true
 sui-test-transaction-builder.workspace = true
 serde_json.workspace = true
 
+[target.'cfg(msim)'.dependencies]
+msim.workspace = true
+
 [package.metadata.cargo-udeps.ignore]
 normal = ["jemalloc-ctl"]
 
@@ -92,6 +104,10 @@ name = "generate-genesis-checkpoint"
 path = "src/generate_genesis_checkpoint.rs"
 test = false
 
+[[test]]
+name = "ptb_files_tests"
+harness = false
+
 [features]
 gas-profiler = [
     "sui-types/gas-profiler",

diff --git a/crates/sui/src/client_commands.rs b/crates/sui/src/client_commands.rs
@@ -1,6 +1,7 @@
 // Copyright (c) Mysten Labs, Inc.
 // SPDX-License-Identifier: Apache-2.0
 
+use crate::client_ptb::ptb::{ptb_description, PTB};
 use std::{
     collections::{btree_map::Entry, BTreeMap},
     fmt::{Debug, Display, Formatter, Write},
@@ -18,7 +19,6 @@ use fastcrypto::{
     traits::ToFromBytes,
 };
 
-use json_to_table::json_to_table;
 use move_core_types::language_storage::TypeTag;
 use move_package::BuildConfig as MoveBuildConfig;
 use prometheus::Registry;
@@ -32,24 +32,21 @@ use shared_crypto::intent::Intent;
 use sui_execution::verifier::VerifierOverrides;
 use sui_json::SuiJsonValue;
 use sui_json_rpc_types::{
-    Coin, DynamicFieldPage, SuiCoinMetadata, SuiData, SuiObjectData, SuiObjectResponse,
-    SuiObjectResponseQuery, SuiParsedData, SuiRawData, SuiTransactionBlockEffectsAPI,
-    SuiTransactionBlockResponse, SuiTransactionBlockResponseOptions,
+    Coin, DynamicFieldPage, SuiCoinMetadata, SuiData, SuiExecutionStatus, SuiObjectData,
+    SuiObjectDataOptions, SuiObjectResponse, SuiObjectResponseQuery, SuiParsedData, SuiRawData,
+    SuiTransactionBlockEffectsAPI, SuiTransactionBlockResponse, SuiTransactionBlockResponseOptions,
 };
-use sui_json_rpc_types::{SuiExecutionStatus, SuiObjectDataOptions};
 use sui_keys::keystore::AccountKeystore;
 use sui_move_build::{
     build_from_resolution_graph, check_invalid_dependencies, check_unpublished_dependencies,
     gather_published_ids, BuildConfig, CompiledPackage, PackageDependencies, PublishedAtError,
 };
 use sui_replay::ReplayToolCommand;
-use sui_sdk::SuiClient;
 use sui_sdk::{
+    apis::ReadApi,
     sui_client_config::{SuiClientConfig, SuiEnv},
-    SUI_COIN_TYPE,
-};
-use sui_sdk::{
-    wallet_context::WalletContext, SUI_DEVNET_URL, SUI_LOCAL_NETWORK_URL, SUI_TESTNET_URL,
+    wallet_context::WalletContext,
+    SUI_COIN_TYPE, SUI_DEVNET_URL, SUI_LOCAL_NETWORK_URL, SUI_TESTNET_URL,
 };
 use sui_types::{
     base_types::{ObjectID, SequenceNumber, SuiAddress},
@@ -67,6 +64,7 @@ use sui_types::{
     transaction::{SenderSignedData, Transaction, TransactionData, TransactionDataAPI},
 };
 
+use json_to_table::json_to_table;
 use tabled::{
     builder::Builder as TableBuilder,
     settings::{
@@ -436,6 +434,10 @@ pub enum SuiClientCommands {
         serialize_signed_transaction: bool,
     },
 
+    /// Run a PTB either from file or from the provided args
+    #[clap(name = "ptb")]
+    PTB(PTB),
+
     /// Publish Move modules
     #[clap(name = "publish")]
     Publish {
@@ -958,57 +960,18 @@ impl SuiClientCommands {
                 let sender = sender.unwrap_or(context.active_address()?);
 
                 let client = context.get_client().await?;
-                let (dependencies, compiled_modules, compiled_package, package_id) =
-                    compile_package(
-                        &client,
+
+                let (package_id, compiled_modules, dependencies, package_digest, upgrade_policy) =
+                    upgrade_package(
+                        client.read_api(),
                         build_config,
                         package_path,
+                        upgrade_capability,
                         with_unpublished_dependencies,
                         skip_dependency_verification,
                     )
                     .await?;
 
-                let package_id = package_id.map_err(|e| match e {
-                    PublishedAtError::NotPresent => {
-                        anyhow!("No 'published-at' field in manifest for package to be upgraded.")
-                    }
-                    PublishedAtError::Invalid(v) => anyhow!(
-                        "Invalid 'published-at' field in manifest of package to be upgraded. \
-                         Expected an on-chain address, but found: {v:?}"
-                    ),
-                })?;
-
-                let resp = context
-                    .get_client()
-                    .await?
-                    .read_api()
-                    .get_object_with_options(
-                        upgrade_capability,
-                        SuiObjectDataOptions::default().with_bcs().with_owner(),
-                    )
-                    .await?;
-
-                let Some(data) = resp.data else {
-                    return Err(anyhow!(
-                        "Could not find upgrade capability at {upgrade_capability}"
-                    ));
-                };
-
-                let upgrade_cap: UpgradeCap = data
-                    .bcs
-                    .ok_or_else(|| {
-                        anyhow!("Fetch upgrade capability object but no data was returned")
-                    })?
-                    .try_as_move()
-                    .ok_or_else(|| anyhow!("Upgrade capability is not a Move Object"))?
-                    .deserialize()?;
-                // We keep the existing policy -- no fancy policies or changing the upgrade
-                // policy at the moment. To change the policy you can call a Move function in the
-                // `package` module to change this policy.
-                let upgrade_policy = upgrade_cap.policy;
-                let package_digest =
-                    compiled_package.get_package_digest(with_unpublished_dependencies);
-
                 let data = client
                     .transaction_builder()
                     .upgrade(
@@ -1061,7 +1024,7 @@ impl SuiClientCommands {
 
                 let client = context.get_client().await?;
                 let (dependencies, compiled_modules, _, _) = compile_package(
-                    &client,
+                    client.read_api(),
                     build_config,
                     package_path,
                     with_unpublished_dependencies,
@@ -1630,6 +1593,16 @@ impl SuiClientCommands {
 
                 SuiClientCommandResult::VerifySource
             }
+            SuiClientCommands::PTB(ptb) => {
+                if ptb.args.contains(&"--help".to_string()) {
+                    ptb_description().print_long_help().unwrap();
+                } else if ptb.args.contains(&"-h".to_string()) || ptb.args.is_empty() {
+                    ptb_description().print_help().unwrap();
+                } else {
+                    ptb.execute(context).await?;
+                }
+                SuiClientCommandResult::NoOutput
+            }
         });
         ret
     }
@@ -1661,8 +1634,69 @@ fn compile_package_simple(
     )?)
 }
 
-async fn compile_package(
-    client: &SuiClient,
+pub(crate) async fn upgrade_package(
+    read_api: &ReadApi,
+    build_config: MoveBuildConfig,
+    package_path: PathBuf,
+    upgrade_capability: ObjectID,
+    with_unpublished_dependencies: bool,
+    skip_dependency_verification: bool,
+) -> Result<(ObjectID, Vec<Vec<u8>>, PackageDependencies, [u8; 32], u8), anyhow::Error> {
+    let (dependencies, compiled_modules, compiled_package, package_id) = compile_package(
+        read_api,
+        build_config,
+        package_path,
+        with_unpublished_dependencies,
+        skip_dependency_verification,
+    )
+    .await?;
+
+    let package_id = package_id.map_err(|e| match e {
+        PublishedAtError::NotPresent => {
+            anyhow!("No 'published-at' field in manifest for package to be upgraded.")
+        }
+        PublishedAtError::Invalid(v) => anyhow!(
+            "Invalid 'published-at' field in manifest of package to be upgraded. \
+                         Expected an on-chain address, but found: {v:?}"
+        ),
+    })?;
+
+    let resp = read_api
+        .get_object_with_options(
+            upgrade_capability,
+            SuiObjectDataOptions::default().with_bcs().with_owner(),
+        )
+        .await?;
+
+    let Some(data) = resp.data else {
+        return Err(anyhow!(
+            "Could not find upgrade capability at {upgrade_capability}"
+        ));
+    };
+
+    let upgrade_cap: UpgradeCap = data
+        .bcs
+        .ok_or_else(|| anyhow!("Fetch upgrade capability object but no data was returned"))?
+        .try_as_move()
+        .ok_or_else(|| anyhow!("Upgrade capability is not a Move Object"))?
+        .deserialize()?;
+    // We keep the existing policy -- no fancy policies or changing the upgrade
+    // policy at the moment. To change the policy you can call a Move function in the
+    // `package` module to change this policy.
+    let upgrade_policy = upgrade_cap.policy;
+    let package_digest = compiled_package.get_package_digest(with_unpublished_dependencies);
+
+    Ok((
+        package_id,
+        compiled_modules,
+        dependencies,
+        package_digest,
+        upgrade_policy,
+    ))
+}
+
+pub(crate) async fn compile_package(
+    read_api: &ReadApi,
     build_config: MoveBuildConfig,
     package_path: PathBuf,
     with_unpublished_dependencies: bool,
@@ -1713,7 +1747,7 @@ async fn compile_package(
     }
     let compiled_modules = compiled_package.get_package_bytes(with_unpublished_dependencies);
     if !skip_dependency_verification {
-        let verifier = BytecodeSourceVerifier::new(client.read_api());
+        let verifier = BytecodeSourceVerifier::new(read_api);
         if let Err(e) = verifier.verify_package_deps(&compiled_package).await {
             return Err(SuiError::ModulePublishFailure {
                 error: format!(
@@ -2027,6 +2061,7 @@ impl Display for SuiClientCommandResult {
                 writeln!(f, "{}", table)?;
             }
             SuiClientCommandResult::NoOutput => {}
+            SuiClientCommandResult::PTB(_) => {} // this is handled in PTB execute
         }
         write!(f, "{}", writer.trim_end_matches('\n'))
     }
@@ -2283,6 +2318,7 @@ pub enum SuiClientCommandResult {
     Pay(SuiTransactionBlockResponse),
     PayAllSui(SuiTransactionBlockResponse),
     PaySui(SuiTransactionBlockResponse),
+    PTB(SuiTransactionBlockResponse),
     Publish(SuiTransactionBlockResponse),
     RawObject(SuiObjectResponse),
     SerializedSignedTransaction(SenderSignedData),