[0/n][transfer-to-object] Transfer to Object Implementation (#12611)

## Description 

This PR implements the core transfer-to-object functionality. In
particular it implements the ability to "receive" an object that was
sent to the address (object ID) of another object using one of the
`transfer` or `transfer_public` functions in the `transfer` module.

More detail is given on the programming model in the attached issue so I
will not go into that.

SDK support for receiving objects has been added in the two PRs stacked
on this one:
* #12987 Adds the `Receiving` type to the json-rpc types, and adds
support receiving objects in the Typescript SDK.
* #12988 Adds support for receiving objects in the Rust SDK
* #13420 Adds pruning of the `per_epoch_object_marker` table at epoch
boundaries

## Test Plan 

I've written a number of tests for this that I believe cover things:
* Execution-correctness tests for this in the transactional tests
* Tests for effect computation in the new sui-core
`transfer_to_object.rs` tests (e.g., receive-then-unwrap,
receive-unwrap-wrap, etc).
* Tests for lock-freeness of receiving arguments (i.e., that the object
identified by the `Receiving` argument is not locked at signing) in the
sui-core `transfer_to_object.rs` tests
* Tests that dependencies are correctly registered, and notified in the
transaction manager for `Receiving` arguments to transactions (see new
tests in the `transaction_manager_tests.rs` file).

A more detailed listing of the tests:
* PTBs
    - Receive object and return to PTB
- Do not do anything with the returned (non-drop) value
[`receive_return_object_dont_touch.move`]
- Call transfer object on it
[`receive_return_object_then_transfer.move`]
- Basic "can receive and then do something in the function"
[`basic_receive.move`]
- Duplicate "Receive" arguments to the PTB
[`duplicate_receive_argument.move`]
    - Pass but don't use `Receiving` argument, then later use it in PTB.
        - By immut ref [`pass_receiver_immut_then_reuse.move`]
        - By mut ref [`pass_receiver_mut_then_reuse.move`]
        - By value and returning it [`pass_through_then_receive.move`]
- Various combinations of receivership being passed
[`receive_by_ref.move`]
(checking borrow/borrow_mut, and restore rules for PTB execution)
    - Receive object of different type [`receive_invalid_type.move`]
- Receive object with non-address owner ownership
[`receive_object_owner.move`]
- Reuse of input receiving argument
[`take_receiver_then_try_to_reuse.move`]
* Type malleability [`receive_invalid_param_ty.move`]
    - Pass receiver into a non-receiver type
      - primitive type
      - struct type with same layout
      - struct type with different layout
    - Pass non-receiver into a receiver type
      - primitive type
      - struct type with same layout
      - struct type with different layout
* Resource conservation/Effects calculation (both transactional tests
and sui-core tests for explicit effects checks)
  - Do various things with object after receiving it:
- Immediately place it as a dynamic field
[`receive_dof_and_mutate.move`]
- Immediately add a dynamic field to it
[`receive_add_dof_and_mutate.move`]
- Immediately add a dynamic field to it, add as a dynamic field to
parent object, then mutate both [`receive_add_dof_and_mutate.move`]
    - Immediately transfer it [`receive_and_send_back.move`]
    - Immediately delete it [`receive_and_deleted.move`]
    - Immediately wrap it  [`receive_and_wrap.move`]
    - Immediately abort [`receive_and_abort.move`]
    - Don't use it [`receive_by_value_flow_through.move`]
- Receive multiple times in a row making sure effects stay in-sync as
expected [`receive_multiple_times_in_row.move`]
  - Shared objects
- Make sure we can receive if object is transferred to an object which
is already shared [`shared_parent/basic_receive.move`]
- Make sure we can receive if object is transferred to an object which
is then shared [`shared_parent/transfer_then_share.move`]
- Non-usage of receiving object argument off a shared parent object
[`shared_parent/drop_receiving.move`]
- Receive object off of shared parent, add as dynamic field of shared
parent and then mutate through the parent
[`shared_parent/receive_dof_and_mutate.move`]
- Send and receive the same object to the same shared parent multiple
times [`shared_parent/receive_multiple_times_in_row.move`]
- MVCC -- Test that we calculate contained UIDs correctly when we
receive an
    object. This is tested in [`mvcc/receive_object_dof.move`] and
    [`mvcc/receive_object_split_changes_dof.move`]
- Sui core tests checking explicit parts of the calculated effects to
make sure they match what we expect:
- Immediately unwrap then transfer inner object
[`transfer_to_object_tests.rs/test_tto_unwrap_transfer`]
- Immediately unwrap then delete inner object as well
[`transfer_to_object_tests.rs/test_tto_unwrap_delete`]
- Immediately unwrap then add inner object as dynamic field
[`transfer_to_object_tests.rs/test_tto_unwrap_add_as_dynamic_field`]
- Immediately unwrap, then wrap again -- this is part of the above since
adding a dynamic field wraps the object
- Basic object receive [`transfer_to_object_tests/test_tto_transfer`]
- Pass but don't ise Receiving argument
[`transfer_to_object_tests/test_tto_unused_receiver`]
- Pass by different references
[`transfer_to_object_tests/test_tto_pass_receiving_by_refs`]
- Receive and immediately delete
[`transfer_to_object_tests/test_tto_delete`]
- Receive, wrap, and then transfer wrapped object
[`transfer_to_object_tests/test_tto_wrap`]
* Sui Core for object locking and transaction dependendency calculation
in effects
- Test that receiving object arguments are not locked, and that
different
orders of execution for two certs that want to receive the same argument
(but only one is valid) can both be run in either order, and both return
    the same execution effects in either order
    [`transfer_to_object_tests/test_tt_not_locked`]
  - Test that transaction dependencies are added correctly:
    - Basic test that we add transaction dependendency if we execute
      successfully and receive the object
      [`transfer_to_object_tests/test_tto_valid_dependencies`]
    - Similar case for if we delete the object immediately

[`transfer_to_object_tests/test_tto_valid_dependencies_delete_on_receive`]
- That we don't register the transaction dependendency if we don't
receive
      the object
      [`transfer_to_object_tests/test_tto_dependencies_dont_receive`]
- That we don't register the transaction dependendency if we don't
receive
      the object and we abort

[`transfer_to_object_tests/test_tto_dependencies_dont_receive_but_abort`]
- That we register the dependendency if we received the object, even if
we
      then went on to abort in the transaction
[`transfer_to_object_tests/test_tto_dependencies_receive_and_abort`]
- Dynamic object field spoofing: make sure we don't accidentally
register a
dynamic object field load of an object that we want to receive at a
different version as a receivership of that object (i.e., don't register
      the transaction dependendency)
      [`transfer_to_object_tests/receive_and_dof_interleave`]

## Additional tests 
- PTBs
    - `MakeMoveVec`:
        - create but don't use [receive_many_move_vec.move]
- pass vec by value but don't receive [receive_many_move_vec.move]
- pass vec by ref then use value to receive in later command
[receive_many_move_vec.move]
- Pass vec by mut ref and pop/receive some, then receive rest in other
call [receive_many_move_vec.move]
- Pass vec by mut ref, only receive some [receive_many_move_vec.move]
- Pass vec by value, only receive some [receive_many_move_vec.move]
        - Pass vec by value, receive all [receive_many_move_vec.move]
- Pack receiving tickets into a struct (some/all) then receive
transitively [receive_duo_struct.move]
- Type mismatches:
- Receiving and phony struct with same struct layout and right type args
([receive_invalid_param_ty.move])
- Receiving with mismatched type args [move_vec_receiving_types.move]
- Receiving with multiple different type args
[move_vec_receiving_types.move]
- `TransferObjects`
- Try to transfer receiving ticket [receive_ticket_coin_operations.move]
- `SplitCoins`
- Try to split a receiving ticket [receive_ticket_coin_operations.move]
- `MergeCoins`
- Try to merge a receiving ticket [receive_ticket_coin_operations.move]
    
- MVCC [`receive_object_access_through_parent[dof/df].move`]
- Transaction input checks (in sui-core tests)
- Delete between cert and execution [tests in `test_tto_not_locked`in
the sui-core tests
- Cert denial if sending a transaction where `input_objects \intersect
receiving_object !=
{}` [`test_tto_intersection_input_and_receiving_objects`]
- Type-fixing for receiving arguments [pt_receive_type_fixing.move]

---
If your changes are not user-facing and not a breaking change, you can
skip the following section. Otherwise, please indicate what changed, and
then add to the Release Notes section as highlighted during the release
process.

### Type of Change (Check all that apply)

- [X] protocol change
- [X] user-visible impact
- [ ] breaking change for a client SDKs
- [X] breaking change for FNs (FN binary must upgrade)
- [X] 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 the ability to receive objects off of another object. This is
currently only turned on in devnet. More information on
transfer-to-object, receiving objects off of other objects, and current SDK support can be
found in the GitHub issue which can be found here:
MystenLabs/sui#12658

Author: tzakian

crates/sui-framework/docs/transfer.md

@@ -5,21 +5,65 @@
 
 
 
+-  [Struct `Receiving`](#0x2_transfer_Receiving)
 -  [Constants](#@Constants_0)
 -  [Function `transfer`](#0x2_transfer_transfer)
 -  [Function `public_transfer`](#0x2_transfer_public_transfer)
 -  [Function `freeze_object`](#0x2_transfer_freeze_object)
 -  [Function `public_freeze_object`](#0x2_transfer_public_freeze_object)
 -  [Function `share_object`](#0x2_transfer_share_object)
 -  [Function `public_share_object`](#0x2_transfer_public_share_object)
+-  [Function `receive`](#0x2_transfer_receive)
 -  [Function `freeze_object_impl`](#0x2_transfer_freeze_object_impl)
 -  [Function `share_object_impl`](#0x2_transfer_share_object_impl)
 -  [Function `transfer_impl`](#0x2_transfer_transfer_impl)
+-  [Function `receive_impl`](#0x2_transfer_receive_impl)
 
 
-<pre><code></code></pre>
+<pre><code><b>use</b> <a href="object.md#0x2_object">0x2::object</a>;
+</code></pre>
+
+
+
+<a name="0x2_transfer_Receiving"></a>
+
+## Struct `Receiving`
+
+This represents the ability to <code>receive</code> an object of type <code>T</code>.
+This type is ephemeral per-transaction and cannot be stored on-chain.
+This does not represent the obligation to receive the object that it
+references, but simply the ability to receive the object with object ID
+<code>id</code> at version <code>version</code> if you can prove mutable access to the parent
+object during the transaction.
+Internals of this struct are opaque outside this module.
+
+
+<pre><code><b>struct</b> <a href="transfer.md#0x2_transfer_Receiving">Receiving</a>&lt;T: key&gt; <b>has</b> drop
+</code></pre>
+
+
+
+<details>
+<summary>Fields</summary>
+
 
+<dl>
+<dt>
+<code>id: <a href="object.md#0x2_object_ID">object::ID</a></code>
+</dt>
+<dd>
 
+</dd>
+<dt>
+<code>version: u64</code>
+</dt>
+<dd>
+
+</dd>
+</dl>
+
+
+</details>
 
 <a name="@Constants_0"></a>
 
@@ -211,6 +255,37 @@ The object must have <code>store</code> to be shared outside of its module.
 
 
 
+</details>
+
+<a name="0x2_transfer_receive"></a>
+
+## Function `receive`
+
+Given mutable (i.e., locked) access to the <code>parent</code> and a <code><a href="transfer.md#0x2_transfer_Receiving">Receiving</a></code> argument
+referencing an object of type <code>T</code> owned by <code>parent</code> use the <code>to_receive</code>
+argument to receive and return the referenced owned object of type <code>T</code>.
+
+
+<pre><code><b>public</b> <b>fun</b> <a href="transfer.md#0x2_transfer_receive">receive</a>&lt;T: key&gt;(parent: &<b>mut</b> <a href="object.md#0x2_object_UID">object::UID</a>, to_receive: <a href="transfer.md#0x2_transfer_Receiving">transfer::Receiving</a>&lt;T&gt;): T
+</code></pre>
+
+
+
+<details>
+<summary>Implementation</summary>
+
+
+<pre><code><b>public</b> <b>fun</b> <a href="transfer.md#0x2_transfer_receive">receive</a>&lt;T: key&gt;(parent: &<b>mut</b> UID, to_receive: <a href="transfer.md#0x2_transfer_Receiving">Receiving</a>&lt;T&gt;): T {
+    <b>let</b> <a href="transfer.md#0x2_transfer_Receiving">Receiving</a> {
+        id,
+        version,
+    } = to_receive;
+    <a href="transfer.md#0x2_transfer_receive_impl">receive_impl</a>(<a href="object.md#0x2_object_uid_to_address">object::uid_to_address</a>(parent), id, version)
+}
+</code></pre>
+
+
+
 </details>
 
 <a name="0x2_transfer_freeze_object_impl"></a>
@@ -326,4 +401,26 @@ The object must have <code>store</code> to be shared outside of its module.
 
 
 
+</details>
+
+<a name="0x2_transfer_receive_impl"></a>
+
+## Function `receive_impl`
+
+
+
+<pre><code><b>fun</b> <a href="transfer.md#0x2_transfer_receive_impl">receive_impl</a>&lt;T: key&gt;(parent: <b>address</b>, to_receive: <a href="object.md#0x2_object_ID">object::ID</a>, version: u64): T
+</code></pre>
+
+
+
+<details>
+<summary>Implementation</summary>
+
+
+<pre><code><b>native</b> <b>fun</b> <a href="transfer.md#0x2_transfer_receive_impl">receive_impl</a>&lt;T: key&gt;(parent: <b>address</b>, to_receive: <a href="object.md#0x2_object_ID">object::ID</a>, version: u64): T;
+</code></pre>
+
+
+
 </details>

crates/sui-framework/packages/sui-framework/sources/transfer.move

@@ -3,12 +3,24 @@
 
 module sui::transfer {
 
-    use sui::object;
+    use sui::object::{Self, ID, UID};
     use sui::prover;
 
     #[test_only]
     friend sui::test_scenario;
 
+    /// This represents the ability to `receive` an object of type `T`.
+    /// This type is ephemeral per-transaction and cannot be stored on-chain.
+    /// This does not represent the obligation to receive the object that it
+    /// references, but simply the ability to receive the object with object ID
+    /// `id` at version `version` if you can prove mutable access to the parent
+    /// object during the transaction.
+    /// Internals of this struct are opaque outside this module.
+    struct Receiving<phantom T: key> has drop {
+        id: ID,
+        version: u64,
+    }
+
     #[allow(unused_const)]
     /// Shared an object that was previously created. Shared objects must currently
     /// be constructed in the transaction they are created.
@@ -70,6 +82,17 @@ module sui::transfer {
         share_object_impl(obj)
     }
 
+    /// Given mutable (i.e., locked) access to the `parent` and a `Receiving` argument
+    /// referencing an object of type `T` owned by `parent` use the `to_receive`
+    /// argument to receive and return the referenced owned object of type `T`.
+    public fun receive<T: key>(parent: &mut UID, to_receive: Receiving<T>): T {
+        let Receiving {
+            id,
+            version,
+        } = to_receive;
+        receive_impl(object::uid_to_address(parent), id, version)
+    }
+
     public(friend) native fun freeze_object_impl<T: key>(obj: T);
 
     spec freeze_object_impl {
@@ -107,4 +130,13 @@ module sui::transfer {
         ensures [abstract] global<object::Ownership>(object::id(obj).bytes).owner == recipient;
         ensures [abstract] global<object::Ownership>(object::id(obj).bytes).status == prover::OWNED;
     }
+
+    native fun receive_impl<T: key>(parent: address, to_receive: object::ID, version: u64): T;
+
+    spec receive_impl {
+        pragma opaque;
+        // TODO: stub to be replaced by actual abort conditions if any
+        aborts_if [abstract] true;
+        // TODO: specify actual function behavior
+    }
 }