[docs] Update entry function docs (MystenLabs#2409)

- Update documentation on entry functions to show TxContext is optional
- Updated some examples
- Fixed some blurbs with regards to entry functions

doc/src/build/move.md

@@ -254,7 +254,7 @@ In general, an entry function, must satisfy the following properties:
 
 - have `public(script)` visibility modifier
 - have no return value
-- have a mutable reference to an instance of the `TxContext` struct
+- (optional) have a mutable reference to an instance of the `TxContext` struct
   defined in the [TxContext module](https://github.com/MystenLabs/sui/blob/main/crates/sui-framework/sources/TxContext.move) as the last parameter
 
 More concretely, the `transfer` function is public, has no return
@@ -267,6 +267,7 @@ value, and has three parameters:
 - `_ctx` - a mutable reference to an instance of the `TxContext`
   struct (in this particular case, this parameter is not actually used
   in the function's body as indicated by its name starting with `_`)
+  - Note that since it is unused, the parameter could be removed. The mutable reference to the `TxContext` is optional for entry functions.
 
 You can see how the `transfer` function is called from a sample Sui
 wallet in [Calling Move code](wallet.md#calling-move-code).

doc/src/build/programming-with-objects/ch2-using-objects.md

@@ -21,13 +21,13 @@ struct ColorObject has key {
 Now let's add this function:
 ```rust
 /// Copies the values of `from_object` into `into_object`.
-public(script) fun copy_into(from_object: &ColorObject, into_object: &mut ColorObject, _ctx: &mut TxContext) {
+public(script) fun copy_into(from_object: &ColorObject, into_object: &mut ColorObject) {
     into_object.red = from_object.red;
     into_object.green = from_object.green;
     into_object.blue = from_object.blue;
 }
 ```
-> :bulb: We added a `&mut TxContext` parameter to the function signature although it's not used. This is to allow the `copy_into` function to be called as an entry function from transactions. The parameter is named with an underscore `_` prefix to tell the compiler that it won't be used and we don't get an unused parameter warning.
+> :bulb: We declared this function as `public(script)` to be callable as an entry function from transactions.
 
 In the above function signature, `from_object` can be a read-only reference because we only need to read its fields; conversely, `into_object` must be a mutable reference since we need to mutate it. In order for a transaction to make a call to the `copy_into` function, **the sender of the transaction must be the owner of both of `from_object` and `into_object`**.
 
@@ -59,7 +59,7 @@ TestScenario::next_tx(scenario, &owner);
     assert!(red == 255 && green == 255 && blue == 255, 0);
 
     let ctx = TestScenario::ctx(scenario);
-    ColorObject::copy_into(&obj2, &mut obj1, ctx);
+    ColorObject::copy_into(&obj2, &mut obj1);
     TestScenario::return_owned(scenario, obj1);
     TestScenario::return_owned(scenario, obj2);
 };
@@ -91,7 +91,7 @@ public fun delete(versioned_id: VersionedID);
 ```
 Let's define a function in the `ColorObject` module that allows us to delete the object:
 ```rust
-    public(script) fun delete(object: ColorObject, _ctx: &mut TxContext) {
+    public(script) fun delete(object: ColorObject) {
         let ColorObject { id, red: _, green: _, blue: _ } = object;
         ID::delete(id);
     }
@@ -111,8 +111,7 @@ let scenario = &mut TestScenario::begin(&owner);
 TestScenario::next_tx(scenario, &owner);
 {
     let object = TestScenario::take_owned<ColorObject>(scenario);
-    let ctx = TestScenario::ctx(scenario);
-    ColorObject::delete(object, ctx);
+    ColorObject::delete(object);
 };
 // Verify that the object was indeed deleted.
 TestScenario::next_tx(scenario, &owner);
@@ -125,11 +124,11 @@ The first part is the same as what we have seen in [Chapter 1](./ch1-object-basi
 #### Option 2. Transfer the object
 The owner of the object may want to transfer it to another account. To support this, the `ColorObject` module will need to define a `transfer` API:
 ```rust
-public(script) fun transfer(object: ColorObject, recipient: address, _ctx: &mut TxContext) {
+public(script) fun transfer(object: ColorObject, recipient: address) {
     Transfer::transfer(object, recipient)
 }
 ```
->:bulb: One cannot call `Transfer::transfer` directly in a transaction because it doesn't have `TxContext` as the last parameter, and hence it cannot be called as an entry function.
+>:bulb: One cannot call `Transfer::transfer` directly as it is not a `public(script)` function.
 
 Let's add a test for transferring too. First of all, we create an object in `owner`'s account and then transfer it to a different account `recipient`:
 ```rust

doc/src/build/programming-with-objects/ch3-immutable-objects.md

@@ -16,7 +16,7 @@ After this call, the specified object will become permanently immutable. This is
 
 Let's add an entry function to the [ColorObject](https://github.com/MystenLabs/sui/blob/main/sui_programmability/examples/objects_tutorial/sources/ColorObject.move) module to turn an existing (owned) `ColorObject` into an immutable object:
 ```rust
-public(script) fun freeze_object(object: ColorObject, _ctx: &mut TxContext) {
+public(script) fun freeze_object(object: ColorObject) {
     Transfer::freeze_object(object)
 }
 ```
@@ -39,7 +39,7 @@ Once an object becomes immutable, the rules of who could use this object in Move
 
 Recall that we defined a function that copies the value of one object to another:
 ```rust
-public(script) fun copy_into(from_object: &ColorObject, into_object: &mut ColorObject, _ctx: &mut TxContext);
+public(script) fun copy_into(from_object: &ColorObject, into_object: &mut ColorObject);
 ```
 In this function, anyone can pass an immutable object as the first argument `from_object`, but not the second argument.
 
@@ -87,7 +87,6 @@ In order to examine if this object is indeed immutable, let's introduce a functi
 public(script) fun update(
     object: &mut ColorObject,
     red: u8, green: u8, blue: u8,
-    _ctx: &mut TxContext,
 ) {
     object.red = red;
     object.green = green;

doc/src/build/programming-with-objects/ch5-child-objects.md

@@ -64,7 +64,7 @@ public(script) fun create_parent(ctx: &mut TxContext) {
 Since the `child` field is `Option` type, we can start with `Option::none()`.
 Now we can define an API that makes an object of `Child` a child of an object of `Parent`:
 ```rust
-public(script) fun add_child(parent: &mut Parent, child: Child, _ctx: &mut TxContext) {
+public(script) fun add_child(parent: &mut Parent, child: Child) {
     let child_ref = Transfer::transfer_to_object(child, parent);
     Option::fill(&mut parent.child, child_ref);
 }
@@ -111,8 +111,8 @@ We have explained in the first chapter that, in order to use an owned object, th
 
 Let's look at how we could use the child object created earlier. Let's define two entry functions:
 ```rust
-public(script) fun mutate_child(_child: &mut Child, _ctx: &mut TxContext) {}
-public(script) fun mutate_child_with_parent(_child: &mut Child, _parent: &mut Parent, _ctx: &mut TxContext) {}
+public(script) fun mutate_child(_child: &mut Child) {}
+public(script) fun mutate_child_with_parent(_child: &mut Child, _parent: &mut Parent) {}
 ```
 The first function requires only one object argument, which is a `Child` object. The second function requires two arguments, a `Child` object and a `Parent` object. Both functions are made empty since what we care about here is not the mutation logic, but whether you are able to make a call to them at all.
 Both functions will compile successfully, because object ownership relationships are dynamic properties and the compiler cannot forsee them.
@@ -229,7 +229,7 @@ Comparing to the previous API, there are two primary differences:
 
 To see how to use this API, let's define a function that could transfer a child object to a new parent:
 ```rust
-public(script) fun transfer_child(parent: &mut Parent, child: Child, new_parent: &mut Parent, _ctx: &mut TxContext) {
+public(script) fun transfer_child(parent: &mut Parent, child: Child, new_parent: &mut Parent) {
     let child_ref = Option::extract(&mut parent.child);
     let new_child_ref = Transfer::transfer_child_to_object(child, child_ref, new_parent);
     Option::fill(&mut new_parent.child, new_child_ref);
@@ -246,7 +246,7 @@ There are two ways to delete a child object:
 #### Transfer and then delete
 What happens if we try to delete a child directly using what we learned in the first chapter, without taking the child reference? Let's find out. We can define a simple `delete_child` method like this:
 ```rust
-public(script) fun delete_child(child: Child, _parent: &mut Parent, _ctx: &mut TxContext) {
+public(script) fun delete_child(child: Child, _parent: &mut Parent) {
     let Child { id } = child;
     ID::delete(id);
 }
@@ -271,7 +271,7 @@ The function takes both the ID of the child object and the child reference as ar
 Instead of calling `ID::delete` on the `id`, for child object, here we require calling `Transfer::delete_child_object` with the `id` and the child reference.
 To demonstrate how to use this API, we define a function that can delete a parent object and a child object altogether:
 ```rust
-public(script) fun delete_parent_and_child(parent: Parent, child: Child, _ctx: &mut TxContext) {
+public(script) fun delete_parent_and_child(parent: Parent, child: Child) {
     let Parent { id: parent_id, child: child_ref_opt } = parent;
     let child_ref = Option::extract(&mut child_ref_opt);
     Option::destroy_none(child_ref_opt);

doc/src/build/wallet.md

@@ -19,16 +19,16 @@ connect the wallet  client to the DevNet, run the following command:
 ```shell
 $ wallet
 ```
-The wallet will print the following line if the wallet is starting up the 
+The wallet will print the following line if the wallet is starting up the
 first time.
 ```shell
 Config file ["/Users/dir/.sui/sui_config/wallet.conf"] doesn't exist, do you want to connect to a Sui Gateway [y/n]?
 ```
 Type 'y' and then press 'Enter'. You should see the following output:
 ```shell
-Sui Gateway Url (Default to Sui DevNet if not specified) : 
+Sui Gateway Url (Default to Sui DevNet if not specified) :
 ```
-The wallet will prompt for the Gateway URL, press 'Enter' and it will default to the DevNet, 
+The wallet will prompt for the Gateway URL, press 'Enter' and it will default to the DevNet,
 or enter the URL if you want to connect to a Gateway hosted elsewhere.
 
 If you have used the wallet before with a local network, follow the next section to
@@ -360,12 +360,12 @@ When not specified, the active address is used.
 
 ```
 sui>-$ objects
-                 Object ID                  |  Version   |                                Digest                               
+                 Object ID                  |  Version   |                                Digest
 ------------------------------------------------------------------------------------------------------------------------------
  0x0b8a4620426e526fa42995cf26eb610bfe6bf063 |     0      | o#6ea7e2d4bf47b3cc219fdc44bf15530244d3b3d1838d59586c0bb41d3db92221
 
 sui>-$ objects --address 0x913cf36f370613ed131868ac6f9da2420166062e
-                 Object ID                  |  Version   |                                Digest                               
+                 Object ID                  |  Version   |                                Digest
 ------------------------------------------------------------------------------------------------------------------------------
  0x0b8a4620426e526fa42995cf26eb610bfe6bf063 |     0      | o#6ea7e2d4bf47b3cc219fdc44bf15530244d3b3d1838d59586c0bb41d3db92221
 ```
@@ -477,7 +477,7 @@ $ wallet objects --address 0x66af3898e7558b79e115ab61184a958497d1905a
 The result should resemble the following, which shows the object in the format of (`object_id`, `sequence_number`, `object_hash`).
 
 ```shell
-                 Object ID                  |  Version   |                                Digest                               
+                 Object ID                  |  Version   |                                Digest
 ------------------------------------------------------------------------------------------------------------------------------
  0x00a0a5211f6edcf4ba09d23b8a7250072be1edb6 |     0      | o#fbb33b6524d4a648fd5fff8dc93f3d6858945959b710a0893c2b86504b38f731
  0x054c8263c73abd697a0f5aa8990d6d7668ce3d0d |     0      | o#cb99c4b8bb83a0b0111583cd2671f27d6eaeb89f89fd7ae822dc335f1a09e187
@@ -572,7 +572,7 @@ If you inspect a newly created account, you would expect the account does not ow
 
 ```shell
 $ wallet objects --address 0xc72cf3adcc4d11c03079cef2c8992aea5268677a
-                 Object ID                  |  Version   |                                Digest                               
+                 Object ID                  |  Version   |                                Digest
 ------------------------------------------------------------------------------------------------------------------------------
 Showing 0 results.
 ```
@@ -602,7 +602,7 @@ OPTIONS:
 
 To transfer a coin object to a recipient, you will need the recipient's address,
 the object ID of the coin that you want to transfer,
-and optionally the coin object ID for the transaction fee payment. If a gas 
+and optionally the coin object ID for the transaction fee payment. If a gas
 coin is not specified, one that meets the budget is picked. Gas budget sets a
 cap for how much gas you want to spend. We are still finalizing our gas metering
 mechanisms. For now, just set something large enough.
@@ -636,7 +636,7 @@ The account will now have one object:
 
 ```shell
 $ wallet objects --address 0xc72cf3adcc4d11c03079cef2c8992aea5268677a
-                 Object ID                  |  Version   |                                Digest                               
+                 Object ID                  |  Version   |                                Digest
 ------------------------------------------------------------------------------------------------------------------------------
  0xda2237a9890bccebeeeae0d23ec739f00d2ce2b1 |     0      | o#f77edd77f5c154a850078b81b320870890bbb4f06d18f80fd512b1cc26bc3297
 ```
@@ -723,7 +723,7 @@ $ wallet objects --address 0xef999dbdb19ccca504eef5432cec69ea8a1d4a1b
 And its output:
 
 ```
-                 Object ID                  |  Version   |                                Digest                               
+                 Object ID                  |  Version   |                                Digest
 ------------------------------------------------------------------------------------------------------------------------------
  0x149a3493c97fafc696526052fe08e77043d4be0b |     0      | o#2d50f098c913e1863ece507dcdcd5a291252f6c1df89ec8f16c62b542ac723b5
  0x1b19f74ad77a95d7562432f6991ac9ec1ea2c57c |     0      | o#d390dc554759f892a714b2659046f3f47830cd789b3ec1df9d40bd876c3e1352
@@ -788,7 +788,7 @@ $ wallet objects --address 0x45cda12e3bafe3017b4b3cd62c493e5fbaad7fb0
 
 With output resembling:
 
-```                 Object ID                  |  Version   |                                Digest                               
+```                 Object ID                  |  Version   |                                Digest
 ------------------------------------------------------------------------------------------------------------------------------
  0x13347bd461e8a2b9ee5de7f6131063a3050a45c4 |     0      | o#4ca351cbf507cac8162cb8278a38c1c9cdf4c6d2be05f2bee405da02ce8a4aa1
  0xb402f52ba6216a770939e6d4922ae6d6d05c2256 |     0      | o#b95d120c36fab571c2389bccf507530a39e0055cdd9e9793aaf4ef691b1b8c96
@@ -828,7 +828,7 @@ New Coins : Coin { id: 0x72129fbf3168c37a4dd8ec7ee69da28d0d4d4636, value: 5000 }
 Updated Gas : Coin { id: 0xb402f52ba6216a770939e6d4922ae6d6d05c2256, value: 99780 }
 
 $ wallet objects --address 0x45cda12e3bafe3017b4b3cd62c493e5fbaad7fb0
-                 Object ID                  |  Version   |                                Digest                               
+                 Object ID                  |  Version   |                                Digest
 ------------------------------------------------------------------------------------------------------------------------------
  0x13347bd461e8a2b9ee5de7f6131063a3050a45c4 |     1      | o#4f86a454ed9aa482adcbfece78cdd77d491d4e768aa8034af78a237d18e09f9f
  0x72129fbf3168c37a4dd8ec7ee69da28d0d4d4636 |     1      | o#247905d1c8eee09b4d3bd02f4229376cd7482705e28ef7ff4ca86774d09c72b8
@@ -852,7 +852,7 @@ for the first look at Move source code and a description of the
 following function we will be calling in this tutorial:
 
 ```rust
-public(script) fun transfer(c: Coin::Coin<SUI>, recipient: address, _ctx: &mut TxContext) {
+public(script) fun transfer(c: Coin::Coin<SUI>, recipient: address) {
     Coin::transfer(c, Address::new(recipient))
 }
 ```
@@ -866,7 +866,7 @@ Let us examine objects owned by address `0xae6fb6036570fec1df71599740c132cdf5b45
 
 ```shell
 $ wallet objects --address ae6fb6036570fec1df71599740c132cdf5b45b9d
-                 Object ID                  |  Version   |                                Digest                               
+                 Object ID                  |  Version   |                                Digest
 ------------------------------------------------------------------------------------------------------------------------------
  0x5044dc15d3c71d500116eb026e8b70d0a180f3ac |     0      | o#748fabf1f7f92c8d00b54f5b431fd4e28d9dfd642cc0bc5c48b16dc0efdc58c1
  0x749e3ee0e0ac93bfc06ed58972efe87717a428da |     0      | o#05efb7971ec89b78fd512913fb6f9bfbd0b5ffd2e99775493f9703ff153b3998
@@ -948,7 +948,7 @@ the sender:
 
 ```shell
 $ wallet objects --address 0xae6fb6036570fec1df71599740c132cdf5b45b9d
-                 Object ID                  |  Version   |                                Digest                               
+                 Object ID                  |  Version   |                                Digest
 ------------------------------------------------------------------------------------------------------------------------------
  0x749e3ee0e0ac93bfc06ed58972efe87717a428da |     0      | o#05efb7971ec89b78fd512913fb6f9bfbd0b5ffd2e99775493f9703ff153b3998
  0x98765d1cbc66bdfc443aa60b614427470b266b28 |     0      | o#5f1696a263b9c97ba2e50175db0af1052a70943148b697fca98f98781482eba5
@@ -1001,7 +1001,7 @@ $ wallet objects --address 0xae6fb6036570fec1df71599740c132cdf5b45b9d
 Outputting:
 
 ```
-                 Object ID                  |  Version   |                                Digest                               
+                 Object ID                  |  Version   |                                Digest
 ------------------------------------------------------------------------------------------------------------------------------
  0x749e3ee0e0ac93bfc06ed58972efe87717a428da |     0      | o#05efb7971ec89b78fd512913fb6f9bfbd0b5ffd2e99775493f9703ff153b3998
  0x98765d1cbc66bdfc443aa60b614427470b266b28 |     0      | o#5f1696a263b9c97ba2e50175db0af1052a70943148b697fca98f98781482eba5

doc/src/explore/prototypes.md

@@ -180,7 +180,6 @@ GET /object_info?objectId={{monster_id}}
         hunger_level: u64,
         affection_level: u64,
         buddy_level: u8,
-        _ctx: &mut TxContext
     ) {
         self.monster_level = monster_level;
         self.hunger_level = hunger_level;