[book] transfer to object

book/src/SUMMARY.md

@@ -92,7 +92,7 @@
   - [Ability: Store](./storage/store-ability.md)
   - [UID and ID](./storage/uid-and-id.md)
   - [Restricted and Public Transfer](./storage/transfer-restrictions.md)
-  - [Transfer to Object?]() <!-- (./storage/transfer-to-object.md) -->
+  - [Transfer to Object?](./storage/transfer-to-object.md)
 - [Advanced Programmability](./programmability/README.md)
   - [Transaction Context](./programmability/transaction-context.md)
   - [Module Initializer](./programmability/module-initializer.md)

book/src/concepts/what-is-a-transaction.md

@@ -31,21 +31,27 @@ Transactions consist of:
 
 ## Inputs
 
-Transaction inputs are the arguments for the transaction and are split between 2 types:
+Transaction inputs are the arguments for the transaction and are split between 3 types:
+
 - Pure arguments: These are mostly [primitive types](../move-basics/primitive-types.html) with some
-extra additions. A pure argument can be:
-    - [`bool`](../move-basics/primitive-types.html#booleans).
-    - [unsigned integer](../move-basics/primitive-types.html#integer-types) (`u8`, `u16`, `u32`, `u64`, `u128`, `u256`).
-    - [`address`](../move-basics/address.html).
-    - [`std::string::String`](../move-basics/string.html), UTF8 strings.
-    - [`std::ascii::String`](../move-basics/string.html#ascii-strings), ASCII strings.
-    - [`vector<T>`](../move-basics/vector.html), where `T` is a pure type.
-    - [`std::option::Option<T>`](../move-basics/option.html), where `T` is a pure type.
-    - [`std::object::ID`](../storage/uid-and-id.html), typically points to an object. See also [What is an Object](../object/object-model.html).
+  extra additions. A pure argument can be:
+  - [`bool`](../move-basics/primitive-types.html#booleans).
+  - [unsigned integer](../move-basics/primitive-types.html#integer-types) (`u8`, `u16`, `u32`,
+    `u64`, `u128`, `u256`).
+  - [`address`](../move-basics/address.html).
+  - [`std::string::String`](../move-basics/string.html), UTF8 strings.
+  - [`std::ascii::String`](../move-basics/string.html#ascii-strings), ASCII strings.
+  - [`vector<T>`](../move-basics/vector.html), where `T` is a pure type.
+  - [`std::option::Option<T>`](../move-basics/option.html), where `T` is a pure type.
+  - [`std::object::ID`](../storage/uid-and-id.html), typically points to an object. See also
+    [What is an Object](../object/object-model.html).
 - Object arguments: These are objects or references of objects that the transaction will access. An
-object argument needs to be either a shared object, a frozen object, or an object that the
-transaction sender owns, in order for the transaction to be successfull.
-For more see [Object Model](../object/index.html).
+  object argument needs to be either a shared object, a frozen object, or an object that the
+  transaction sender owns, in order for the transaction to be successfull. For more see
+  [Object Model](../object/index.html).
+- Receiving object argument: a special argument that is used to receive an object transferred to
+  another object. We cover this in more detail in the
+  [Transfer to Object](../storage/transfer-to-object.html) section.
 
 ## Commands
 
@@ -95,6 +101,7 @@ The result of the executed transaction consists of different parts:
   status of the transaction, updates to objects and their new versions, the gas object used, the gas
   cost of the transaction, and the events emitted by the transaction;
 - Events - the custom [events](./../programmability/events.md) emitted by the transaction;
-- Object Changes - the changes made to the objects, including the _change of ownership_;
+- Object Changes - the changes made to the objects, including the
+  [_change of ownership_](../storage/storage-functions.md);
 - Balance Changes - the changes made to the aggregate balances of the account involved in the
   transaction;

book/src/move-basics/abilities-introduction.md

@@ -22,7 +22,7 @@ The abilities are separated by commas. Move supports 4 abilities: `copy`, `drop`
 
 ```move
 /// This struct has the `copy` and `drop` abilities.
-struct VeryAble has copy, drop {
+public struct VeryAble has copy, drop {
     // field: Type1,
     // field2: Type2,
     // ...

book/src/storage/transfer-to-object.md

@@ -1,4 +1,132 @@
-# Transfer to Object?
+# Transfer to Object
 
-The `transfer::transfer` call takes the receiver `address` as the second argument, and while in most
-of the cases it is an account address, it can also be an address of an object. In this case,
+Previously, we have explained how [transfer](./storage-functions.md#transfer) works in relation to
+accounts. However, there is an additional behaviour allowed by the
+[Sui Object Model](./../object/object-model.md) - transferring objects to other objects. If certain
+conditions are met (which we explain in this section), objects can be sent to and _received_ from
+other objects.
+
+<div class="warning">
+
+Warning: recipient object must be implemented in a way that allows receiving. Attempt to send an
+object to an object that does not implement receiving can result in asset loss.
+
+</div>
+
+## Background
+
+Every object in Sui has its own `UID` which is represented by the
+[address type](./../move-basics/address.md). This address can be used to query the object's data,
+and to perform account queries, such as getting the list of owned objects. This property of the
+system lays the foundation for the transfer to object feature.
+
+> In this section, by _object address_ we mean the address value stored in the `UID` of the object.
+
+## Transfer to Object
+
+An object can be transferred to another object by calling the `transfer` function, or its public
+version - `public_transfer`. The behaviour is identical to the transfer to account.
+
+```move
+// File: sui-framework/sources/transfer.move
+module sui::transfer;
+
+public fun transfer<T: key>(object: T, recipient: address) {}
+public fun public_transfer<T: key + store>(object: T, recipient: address) {}
+```
+
+## Receiving Objects
+
+While objects _owned by accounts_ can be used in the transaction directly (given that the sender of
+the transaction is the owner), objects transferred to other objects first need to be _received_
+through their owner. The owner object needs to implement a custom function that will call the
+`receive` function from the `transfer` module.
+
+```move
+// File: sui-framework/sources/transfer.move
+module sui::transfer;
+
+/// Special type which cannot be constructed in Move but can be passed as a
+/// special input to a PTB.
+public struct Receiving<phantom T: key> has drop {
+    id: ID,
+    version: u64,
+}
+
+/// Private receiving function for `key`-only objects.
+public fun receive<T: key>(parent: &mut UID, to_receive: Receiving<T>): T { /* ... */ }
+
+/// Public receiving function for `key + store` objects.
+public fun public_receive<T: key + store>(parent: &mut UID, to_receive: Receiving<T>): {
+  /* ... */
+}
+```
+
+The `Receiving` type is a special type that references an object-owned object. It cannot be
+constructed in Move, and can only be passed as a special input to a
+[Programmable Transaction Block (PTB)](../concepts/what-is-a-transaction.md). The `receive` (or
+`public_receive`) function must be called in order to exchange the `Receiving` instance for the
+actual object.
+
+While this may seem overwhelming, we will demonstrate the feature in a simple example.
+
+## Example
+
+To demonstrate the feature, let's consider a simple `PostOffice` object that can receive any objects
+transferred to it. Given that the transfer itself can be performed on the PTB level, or in a Move
+function, we will focus on the receiving part.
+
+```move
+module book::post_office;
+
+// While the `sui::transfer` module is implicitly imported, the `Receiving` type
+// is not. We need to import it explicitly.
+use sui::transfer::Receiving;
+
+/// The `PostOffice` object that can receive any objects transferred to it via
+/// a custom `receive` function.
+public struct PostOffice has key {
+    id: UID,
+}
+
+/// Voila! The `receive` function can now be called on the `PostOffice` object
+/// to receive any objects transferred to it.
+public fun public_receive<T: key + store>(
+    po: &mut PostOffice,
+    to_receive: Receiving<T>
+): T {
+    transfer::public_receive(&mut po.id, to_receive)
+}
+
+/// For objects without `store` (though, they would require special handling), we
+/// can implement the non-public version of the `receive` function.
+public fun receive<T: key>(po: &mut PostOffice, to_receive: Receiving<T>): T {
+    transfer::receive(&mut po.id, to_receive)
+}
+```
+
+In this example, we have defined a `PostOffice` object that can receive any objects transferred to
+it. We omitted the creation of the `PostOffice` for brevity; additionally, an implementation like
+this would require some authorization to prevent unauthorized claims. We talk about authorization
+patterns in the [Advanced Programmability](./../programmability/) chapter.
+
+## Limitations
+
+Transfer to Object must be used with caution, as the recipient object must be implemented in a way
+that allows receiving. Worth noting, that objects owned by other objects must be taken by value, and
+cannot be borrowed as references, unlike objects owned by accounts.
+
+Transfer to Object is not the only way to create a relationship between objects. There are more
+flexible and feature-rich ways, such as the
+[Dynamic Fields](./../programmability/dynamic-fields.md), which we explore in the
+[Advanced Programmability](./../programmability/) chapter.
+
+## Summary
+
+- Objects can be transferred to other objects by calling the `transfer` function.
+- The recipient object must be able to `receive` transferred objects, otherwise the objects may be
+  lost.
+- The `Receiving` type is a special type that references an object-owned object. It is passed as a
+  special input to a transaction and cannot be constructed dynamically.
+- Once received, the object can be used normally, including being transferred again, even to the
+  same parent object.

packages/samples/sources/move-basics/assert-and-abort.move

@@ -18,6 +18,9 @@ if (!user_has_access) {
 if (user_has_access) {
    abort(1)
 };
+
+// abort may also come without a code
+abort
 // ANCHOR_END: abort
 }
 
@@ -68,4 +71,4 @@ public fun update_value(user: &mut User, value: u64) {
     user.value = value;
 }
 // ANCHOR_END: error_attribute
-}
+

packages/samples/sources/move-basics/struct.move

@@ -4,7 +4,7 @@
 #[allow(unused_variable, unused_field)]
 module book::struct_syntax;
 
-use std::string::{Self, String};
+use std::string::String;
 
 // ANCHOR: def
 /// A struct representing an artist.

packages/samples/sources/programmability/events.move

@@ -29,6 +29,6 @@ public fun purchase(coin: Coin<SUI>, ctx: &mut TxContext) {
     });
 
     // Omitting the rest of the implementation to keep the example simple.
-    abort 0
+    abort
 }
 // ANCHOR_END: emit

packages/samples/sources/programmability/hot-potato-pattern.move

@@ -85,14 +85,14 @@ public fun purchase_phone(ctx: &mut TxContext): (Phone, Ticket) {
 public fun pay_in_bonus_points(ticket: Ticket, payment: Coin<BONUS>) {
     let Ticket { amount } = ticket;
     assert!(payment.value() == amount);
-    abort 0 // omitting the rest of the function
+    abort // omitting the rest of the function
 }
 
 /// The customer may pay for the `Phone` with `USD`.
 public fun pay_in_usd(ticket: Ticket, payment: Coin<USD>) {
     let Ticket { amount } = ticket;
     assert!(payment.value() == amount);
-    abort 0 // omitting the rest of the function
+    abort // omitting the rest of the function
 }
 // ANCHOR_END: phone_shop
 }