From 4f5dba51c00c8a68e8e68468ce65606c29fb989e Mon Sep 17 00:00:00 2001 From: stefan-mysten <135084671+stefan-mysten@users.noreply.github.com> Date: Sun, 27 Oct 2024 21:40:44 -0700 Subject: [PATCH] Add more doc comments --- crates/sui-transaction-builder/src/lib.rs | 43 ++++++++++++++++---- crates/sui-transaction-builder/src/object.rs | 39 ++++++++++++++---- 2 files changed, 67 insertions(+), 15 deletions(-) diff --git a/crates/sui-transaction-builder/src/lib.rs b/crates/sui-transaction-builder/src/lib.rs index c6a69fa4d..571c80e33 100644 --- a/crates/sui-transaction-builder/src/lib.rs +++ b/crates/sui-transaction-builder/src/lib.rs @@ -35,6 +35,7 @@ use sui_types::types::Upgrade; use serde::Serialize; +/// A builder for creating transactions. Use [`try_finish`] to finalize the transaction data. #[derive(Clone, Debug)] pub struct TransactionBuilder { /// The inputs to the transaction. @@ -74,9 +75,13 @@ pub enum Input { /// A separate type to support denoting a function by a more structured representation. pub struct Function { + /// The package that contains the module with the function. package: Address, + /// The module that contains the function. module: Identifier, + /// The function name. function: Identifier, + /// The type arguments for the function. type_args: Vec, } @@ -138,7 +143,13 @@ impl TransactionBuilder { } // Commands - /// Call a Move function with the given arguments. + /// Call a public or a Move function with the given arguments. + /// + /// - `function` is a structured representation of a package::module::function argument. + /// + /// The return value is a result argument that can be used in subsequent commands. + /// If the move call returns multiple results, you can access them using the + /// [`Argument::nested`] method. pub fn move_call(&mut self, function: Function, arguments: Vec) -> Argument { let cmd = Command::MoveCall(MoveCall { package: function.package.into(), @@ -151,7 +162,7 @@ impl TransactionBuilder { Argument::Result(self.commands.len() as u16 - 1) } - /// Transfer a list of objects to the given address. + /// Transfer a list of objects to the given address, without producing any result. pub fn transfer_objects(&mut self, objects: Vec, address: Argument) { let cmd = Command::TransferObjects(TransferObjects { objects: objects.into_iter().collect(), @@ -160,7 +171,9 @@ impl TransactionBuilder { self.commands.push(cmd); } - /// Split a coin by amounts. + /// Splits a coin by the provided amounts, returning multiple results (as many as there are + /// amounts. To access the results, use the [`Argument::nested`] method to access the desired + /// coin by its index. pub fn split_coins(&mut self, coin: Argument, amounts: Vec) -> Argument { let cmd = Command::SplitCoins(SplitCoins { coin, @@ -170,7 +183,7 @@ impl TransactionBuilder { Argument::Result(self.commands.len() as u16 - 1) } - /// Merge a list of coins into a single coin. + /// Merge a list of coins into a single coin, without producing any result. pub fn merge_coins(&mut self, into_coin: Argument, coins: Vec) { let cmd = Command::MergeCoins(MergeCoins { coin: into_coin, @@ -179,7 +192,9 @@ impl TransactionBuilder { self.commands.push(cmd); } - /// Make a move vector from a list of elements. + /// Make a move vector from a list of elements. If the elements are not objects, or the vector + /// is empty, a type must be supplied. + /// It returns the Move vector as an argument, that can be used in subsequent commands. pub fn make_move_vec(&mut self, type_: Option, elements: Vec) -> Argument { let cmd = Command::MakeMoveVector(MakeMoveVector { type_, @@ -189,8 +204,12 @@ impl TransactionBuilder { Argument::Result(self.commands.len() as u16 - 1) } - /// Publish a list of modules with the given dependencies. This requires the upgrade cap to be - /// transferred to sender/another address after this call. + /// Publish a list of modules with the given dependencies. The result is the upgrade cap, which + /// should be transferred to sender/another address after this call. + /// + /// - `modules`: is the bytecode bcs encoded for the modules to be published + /// - `dependencies`: is the list of IDs of the transitive dependencies of the package to be + /// published pub fn publish(&mut self, modules: Vec>, dependencies: Vec) -> Argument { let cmd = Command::Publish(Publish { modules, @@ -200,7 +219,13 @@ impl TransactionBuilder { Argument::Result(self.commands.len() as u16 - 1) } - /// Upgrade a module. + /// Upgrade a Move package. + /// + /// - `modules`: is the bytecode bcs encoded for the modules to be published + /// - `dependencies`: is the list of IDs of the transitive dependencies of the package to be + /// upgraded + /// - `prev`: is the ID of the current package being upgraded + /// - `ticket`: is the upgrade ticket pub fn upgrade( &mut self, modules: Vec>, @@ -914,6 +939,7 @@ mod tests { } wait_for_tx_and_check_effects_status_success(&client, &tx, effects).await; + // updated package. Has a new function. let updated_modules: [u8; 587] = [ 161, 28, 235, 11, 6, 0, 0, 0, 10, 1, 0, 8, 2, 8, 16, 3, 24, 51, 4, 75, 2, 5, 77, 57, 7, 134, 1, 155, 1, 8, 161, 2, 64, 10, 225, 2, 18, 12, 243, 2, 163, 1, 13, 150, 4, 6, 0, 4, @@ -967,6 +993,7 @@ mod tests { } let upgrade_policy = tx.input(Serialized(&0u8)); + // the digest of the new package that was compiled let package_digest = [ 68, 89, 156, 51, 190, 35, 155, 216, 248, 49, 135, 170, 106, 42, 190, 4, 208, 59, 155, 89, 74, 63, 70, 95, 207, 78, 227, 22, 136, 146, 57, 79, diff --git a/crates/sui-transaction-builder/src/object.rs b/crates/sui-transaction-builder/src/object.rs index bffac8c0e..b0f56a15e 100644 --- a/crates/sui-transaction-builder/src/object.rs +++ b/crates/sui-transaction-builder/src/object.rs @@ -10,23 +10,33 @@ use crate::Error; /// Type representing potentially unresolved object types, with a builder API. #[derive(Clone, Debug)] pub struct Object { + /// Unique identifier for the object. pub id: ObjectId, + /// The kind of object. pub kind: Option, + /// The version of the object. pub version: Option, + /// The digest of the object. pub digest: Option, + /// The initial shared version of the object. pub initial_shared_version: Option, + /// Whether the object is mutable. pub mutable: Option, } +/// Specifies the kind of object. #[derive(Clone, Debug)] pub enum Kind { + /// A Move object, either immutable, or owned mutable. ImmOrOwned, + /// A Move object that can be received in this transaction. Receiving, + /// A Move object that's shared and mutable. Shared, } impl Object { - // Minimal information + /// Return an object with only its ID. pub fn by_id(id: ObjectId) -> Self { Self { id, @@ -38,7 +48,7 @@ impl Object { } } - // Fully resolved + // Return an owned kind of object with all required fields. pub fn owned(id: ObjectId, version: u64, digest: ObjectDigest) -> Self { Self { id, @@ -50,6 +60,7 @@ impl Object { } } + /// Return an immutable kind of object with all required fields. pub fn immutable(id: ObjectId, version: u64, digest: ObjectDigest) -> Self { Self { id, @@ -61,6 +72,7 @@ impl Object { } } + /// Return a receiving kind of object with all required fields. pub fn receiving(id: ObjectId, version: u64, digest: ObjectDigest) -> Self { Self { id, @@ -72,6 +84,9 @@ impl Object { } } + /// Return a shared object. + /// - `mutable` controls whether caller asks for a mutable reference to shared object. + /// - `initial_shared_version` is the version of the object when it became shared. pub fn shared(id: ObjectId, initial_shared_version: u64, mutable: bool) -> Self { Self { id, @@ -85,7 +100,7 @@ impl Object { // Add partial information - // Kind + /// Return the object as an owned kind of object. pub fn as_owned(self) -> Self { Self { kind: Some(Kind::ImmOrOwned), @@ -96,7 +111,8 @@ impl Object { ..self } } - // Redundant, but who ever liked saying "imm_or_owned"? + + /// Return the object as an immutable kind of object. pub fn as_immutable(self) -> Self { Self { kind: Some(Kind::ImmOrOwned), @@ -108,6 +124,7 @@ impl Object { } } + /// Return the object as a receiving kind of object. pub fn as_receiving(self) -> Self { Self { kind: Some(Kind::Receiving), @@ -117,6 +134,7 @@ impl Object { } } + /// Return the object as a shared kind of object. pub fn as_shared(self) -> Self { Self { kind: Some(Kind::Shared), @@ -126,7 +144,7 @@ impl Object { } } - // ObjectRef fields + /// Return the object with the specified version. pub fn versioned_at(self, version: u64) -> Self { Self { version: Some(version), @@ -134,6 +152,7 @@ impl Object { } } + /// Return the object with this specified digest. pub fn with_digest(self, digest: ObjectDigest) -> Self { Self { digest: Some(digest), @@ -143,7 +162,7 @@ impl Object { // Shared fields - // Initial shared version + /// Return the object with the specified initial shared version. pub fn shared_at(self, i: u64) -> Self { Self { initial_shared_version: Some(i), @@ -151,19 +170,25 @@ impl Object { } } - // Shared value mutability + /// Return the shared object after setting `mutable` to true when the input is used by value. pub fn by_val(self) -> Self { Self { mutable: Some(true), ..self } } + + /// Return the shared object after setting `mutable` to false when the input is used by + /// reference. pub fn by_ref(self) -> Self { Self { mutable: Some(false), ..self } } + + /// Return the shared object after setting `mutable` to true when the input is used by mutable + /// reference. pub fn by_mut(&mut self) -> &mut Self { self.mutable = Some(true); self