Skip to content

Commit

Permalink
Add more doc comments
Browse files Browse the repository at this point in the history
  • Loading branch information
stefan-mysten committed Oct 28, 2024
1 parent 587fa39 commit 4f5dba5
Show file tree
Hide file tree
Showing 2 changed files with 67 additions and 15 deletions.
43 changes: 35 additions & 8 deletions crates/sui-transaction-builder/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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<TypeTag>,
}

Expand Down Expand Up @@ -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>) -> Argument {
let cmd = Command::MoveCall(MoveCall {
package: function.package.into(),
Expand All @@ -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<Argument>, address: Argument) {
let cmd = Command::TransferObjects(TransferObjects {
objects: objects.into_iter().collect(),
Expand All @@ -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>) -> Argument {
let cmd = Command::SplitCoins(SplitCoins {
coin,
Expand All @@ -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<Argument>) {
let cmd = Command::MergeCoins(MergeCoins {
coin: into_coin,
Expand All @@ -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<TypeTag>, elements: Vec<Argument>) -> Argument {
let cmd = Command::MakeMoveVector(MakeMoveVector {
type_,
Expand All @@ -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<Vec<u8>>, dependencies: Vec<ObjectId>) -> Argument {
let cmd = Command::Publish(Publish {
modules,
Expand All @@ -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<Vec<u8>>,
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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,
Expand Down
39 changes: 32 additions & 7 deletions crates/sui-transaction-builder/src/object.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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<Kind>,
/// The version of the object.
pub version: Option<u64>,
/// The digest of the object.
pub digest: Option<ObjectDigest>,
/// The initial shared version of the object.
pub initial_shared_version: Option<u64>,
/// Whether the object is mutable.
pub mutable: Option<bool>,
}

/// 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,
Expand All @@ -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,
Expand All @@ -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,
Expand All @@ -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,
Expand All @@ -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,
Expand All @@ -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),
Expand All @@ -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),
Expand All @@ -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),
Expand All @@ -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),
Expand All @@ -126,14 +144,15 @@ impl Object {
}
}

// ObjectRef fields
/// Return the object with the specified version.
pub fn versioned_at(self, version: u64) -> Self {
Self {
version: Some(version),
..self
}
}

/// Return the object with this specified digest.
pub fn with_digest(self, digest: ObjectDigest) -> Self {
Self {
digest: Some(digest),
Expand All @@ -143,27 +162,33 @@ 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),
..self
}
}

// 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
Expand Down

0 comments on commit 4f5dba5

Please sign in to comment.