Transfer to Object

[tzakian]

Transfer to Object

Motivation & Overview

Currently, objects can be transferred to any address using the sui::transfer::transfer and sui::transfer::public_transfer functions. Objects that have been transferred to an account address become owned by that account and transactions sent from that account can use the object. However, if the address that was transferred to belongs to another object instead of an account, the sent object (currently) becomes inaccessible.

The goal of Transfer to Object is to allow accessing or “receiving” objects that have been sent to another object. It does so by establishing a form of parent-child authentication relationship, and allowing objects that have been transferred to an object to be received by the (possibly transitive) owner of the parent object.

The access control for receiving an object that has been sent to another object is defined by the module that defines the type of the parent (receiving) object. These restrictions for accessing sent "child" objects are enforced dynamically through providing mutable access to the parent object's UID during execution. This supports sending to and receiving from owned objects, dynamic field objects and wrapped objects. Sending to Shared Objects is also planned to be supported.

One of the benefits that Transfer to Object seeks to provide is the ability to have a stable ID for e.g., an on-chain wallet or account that can be transferred and remains stable whatever the state of the object that is being sent to; if an object is transferred all of that object's child objects move with it, and the object's address remains stable whether it has been transferred, wrapped, or is held as a dynamic field (etc.).

Programming Model

Sending an Owned Object

From a programmability perspective, an object can be transferred to another object using the existing sui::transfer::transfer and sui::transfer::transfer_public functions. From this -- the "sending side" -- there are no programmability changes or additions.

Receiving an Owned Object

Once an object c has been sent to another object p, p must then receive c to do anything with it. To receive the object c a new Receiving(o: ObjectRef) argument type for Programmable Transaction Blocks (PTBs) is needed that takes an Object Reference containing the to-be-received object’s ObjectID, Version, and Digest (just as owned object arguments for PTBs do today). However, Receiving PTB arguments will not be passed as an owned value or mutable reference within the transaction. To explain further we first need to define the core of the receiving interface in Move:

/// The below type and function will be added to the existing `sui::transfer` module.
module sui::transfer {
    ...
    /// Internals of this struct are opaque. NB that this represents the ability
    /// to receive an object of type `T`. Cannot be stored.
    struct Receiving<phantom T: key> has drop { ... }
    ...
    /// Given mutable (i.e., locked) access to the `parent` and a `Receiving`
    /// object referencing an object owned by `parent` discharge the `Receiving` obligation
    /// and return the corresponding object.
    /// NB: &mut UID here allows the defining module of the parent type to
    /// define custom access/permission policies around receiving objects sent
    /// to objects of a type that it defines. You can see this more in the examples.
    public native fun receive<T: key>(parent: &mut UID, object: Receiving<T>): T;
}

Each Receiving argument referring to a sent object of type T in a PTB will result in exactly one Argument whose Move type is a sui::transfer::Receiving<T>. This argument can then be used to receive the sent object of type T with the sui::transfer::receive function.

When the sui::transfer::receive function is called, a mutable reference to the parent object’s UID must be passed. Since there is no way to get a mutable reference to the UID of an object unless the defining module of the object exposes it, this then allows the module that defines the type of the parent object that is receiving the child object to define access control policies and other restrictions on receiving objects that have been sent to it (see the Shared Object Authorization example below for an example of this pattern). The fact that the passed-in UID actually owns the object referenced by the Receiving parameter is dynamically checked and enforced. This allows access to objects that have been sent to, e.g., dynamic fields where the ownership chain can only be established dynamically.

Note: since sui::transfer::Receiving only has the drop ability, the existence of a Receiving<T> argument represents the ability, but not the obligation to receive the object of type T specified by the Object Reference in the PTB's Receiving argument during that transaction. Some, none, or all Receiving arguments in a PTB can be used without issue. Any object that corresponds to a Receiving argument will remain untouched (in particular, its object reference will remain the same) unless it is received.

SDK Support

Typescript

From an SDK standpoint, when creating transactions you will interact with Receiving transaction inputs almost exactly as you would with either object or ObjectRef in the Typescript SDK. For example, if in the Basic Account example below you wanted to send a transaction that received a coin object with ID 0xc0ffee that was sent to your account at 0xcafe you could do so with the following:

... // boilerplate includes and setup
const tx = new TransactionBlock();
tx.moveCall({
  target: `${examplePackageId}::account::accept_payment`,
  arguments: [tx.object("0xcafe"), tx.object("0xc0ffee")]
});
const result = await signer.signAndExecuteTransactionBlock({
      transactionBlock: tx,
  });
...

Additionally just as with object arguments that also have an ObjectRef constructor where you provide an explicit object ID, version, and digest if you want, there is also a ReceivingRef that takes the same arguments corresponding to a receiving argument.

Rust

Similarly to the typescript case you will create and interact with Receiving transaction inputs in much the same way you would create and interact with object inputs to a transaction. For example if we wanted to same example that we had in Typescript above but using the Rust SDK and accepting a SUI coin that was sent to it, it would look something like the following:

... // setup client as normal
client
  .transaction_builder()
  .move_call(
     sending_account,
     example_package_id,
     "account",
     "accept_payment",
     vec!["0x2::sui::SUI"],
     vec![
       SuiJsonValue::from_object_id("0xcafe"),
       SuiJsonValue::from_object_id("0xc0ffee")
     ],
   ...)

RPC

Additionally, since object-owned objects are representationally the same on-chain as normal owned objects today, existing RPC-functionality for owned objects works for them out of the box the same as today. E.g., callingsui_getOwnedObjects on an address that corresponds to an object O will return the list of all objects that are owned by the object O.

Examples

Basic Account

Below is a basic Account abstraction that could be built with the functionality defined in the transfer module above for receiving objects transferred to another object. Importantly, the address that coins would be sent to would remain the same regardless of whether the Account object was transferred, wrapped, moved to a dynamic field etc. In particular there is a stable ID for a given Account object across the object's lifecycle.

module examples::account {
    use sui::transfer::{Self, Receiving};
    use sui::coin::{Self, Coin};
    use sui::object;
    use sui::dynamic_field as df;
    use sui::tx_context::TxContext;

    const EBalanceDNE: u64 = 1;

    /// Account object that `Coin`s can be sent to. Balances of different types
    /// are held as dynamic fields indexed by the `Coin` type's `type_name`.
    struct Account has key {
        id: object::UID,
    }

    /// Dynamic field key representing a balance of a particular coin type.
    struct AccountBalance<phantom T> has copy, drop, store { }

    /// Accept a coin sent to the `Account` object and then join it to the balance for each coin type.
    /// Dynamic fields are used to index the balances by their coin type.
    public fun accept_payment<T>(account: &mut Account, sent: Receiving<Coin<T>>) {
        // Receive the coin
        let coin = transfer::receive(&mut account.id, sent);
        let account_balance_type = AccountBalance<T>{};
        let account_uid = &mut account.id;

        // If a balance of that type already exists, then add to it, otherwise create one.
        if (df::exists_(account_uid, account_balance_type)) {
            let balance: &mut Coin<T> = df::borrow_mut(account_uid, account_balance_type);
            coin::join(balance, coin);
        } else {
            df::add(account_uid, account_balance_type, coin);
        }
    }

    /// Withdraw `amount` of coins of type `T` from `account`.
    public fun withdraw<T>(account: &mut Account, amount: u64, ctx: &mut TxContext): Coin<T> {
        let account_balance_type = AccountBalance<T>{};
        let account_uid = &mut account.id;
        // Make sure what we are withdrawing exists
        assert!(df::exists_(account_uid, account_balance_type), EBalanceDNE);
        let balance: &mut Coin<T> = df::borrow_mut(account_uid, account_balance_type);
        coin::split(balance, amount, ctx)
    }

    /// Can transfer this account to a different address
    /// (e.g., to another non-object address, or to another object). 
    public fun transfer_account(account: Account, to: address, _ctx: &mut TxContext) {
        // Perform some authorization checks here and if they pass then transfer the account
        // ...
        transfer::transfer(account, to);
    }
}

Basic Shared-Object with Authorization to Receive Objects

The below shows how one might enforce authenticated access against a shared object's owned objects. The authorization function would need to be filled in.

module examples::shared_object_auth {
    use sui::transfer::{Self, Receiving};
    use sui::object;
    use sui::tx_context::TxContext;

    struct SharedObject has key {
        id: object::UID,
    }

    struct AccessCap has drop {}

    public fun create(ctx: &mut TxContext) {
        let s = SharedObject { id: object::new(ctx), };
        transfer::share_object(s);
    }

    /// Function that authorizes access to the inbox of the shared object.
    public fun authorize_inbox_access(_ctx: &mut TxContext): AccessCap {
        // Perform some authorization checks here....
        AccessCap {}
    }

    /// If the ability to receive objects sent to the shared object in this transaction has been granted, then
    /// the transaction can use the `AccessCap` to retrieve the sent object (and they will then need to do something with it).
    public fun receive_object<T: key>(obj: &mut SharedObject, sent: Receiving<T>, _access_cap: &AccessCap): T {
        transfer::receive(&mut obj.id, sent)
    }
}

Dynamic Authorization and Access to Sent Objects

The below shows an example of accessing objects that have been sent to dynamic fields of another object. In this case, accept_payment_on_named_account will accept a payment of Coin<T> that has been sent to a NamedAccount object that it controls and will then add that coin to the NamedAccount's balance for that coin type.

module examples::account_manager {
    use sui::object::{Self, UID};
    use std::string::String;
    use sui::coin::{Self, Coin};
    use sui::tx_context::TxContext;
    use sui::dynamic_field as df;
    use sui::transfer::{Self, Receiving};

    /// A Named account.
    struct NamedAccount has key, store {
        id: UID,
        name: String,
    }

    /// An account manager that controls (possibly multiple) named accounts.
    /// Each named account can have balances of many different types that it holds.
    struct AccountManager has key {
        id: UID,
    }

    /// Dynamic field key representing a balance of a particular coin type.
    struct AccountBalance<phantom T> has copy, drop, store {}

    /// Accept a payment of type `T` that has been sent to the named account with
    /// name `account_name`. The received payment will be placed under the corresponding
    /// named account's account balances. 
    public fun accept_payment_on_named_account<T: key>(
        account_manager: &mut AccountManager,
        account_name: String,
        sent: Receiving<Coin<T>>,
        ctx: &mut TxContext
    ) {
        // Determine if the named account exists. If not, then add it.
        if (!df::exists_(&account_manager.id, account_name)) {
            df::add(&mut account_manager.id, account_name, NamedAccount {
                id: object::new(ctx),
                name: account_name,
            });
        };

        // Get the named account and receive the payment.
        let named_account: &mut NamedAccount = df::borrow_mut(&mut account_manager.id, account_name);
        let received = transfer::receive(&mut named_account.id, sent);

        // Add the received amount to the account balance. If a balance of that
        // type doesn't exist yet, then create one.
        let account_balance_type = AccountBalance<T>{};
        if (!df::exists_(&named_account.id, account_balance_type)) {
            df::add(&mut named_account.id, account_balance_type, received);
        } else {
            let balance: &mut Coin<T> = df::borrow_mut(&mut named_account.id, account_balance_type);
            coin::join(balance, received);
        };
    }
}

[ISayHelloworld]

I'm not sure i understand right, ppl A wrap the coin into the Receiving struct and send it to ppl B, B accept it in by calling accept payment. but how can A wrap the item to be sent into the Receiving struct? should it provide a "wrap" method?

by the way, this will be very helpful for me to construct a "bag" system in on-chain game.

[tzakian]

Hi @ISayHelloworld

The key insight here is that the Receiving struct does not contain or wrap the object that is transferred. Instead, you can view the Receiving struct as a ticket (or capability) that allows you to retrieve and load the object during execution.

What happens is that when A sends the coin C to B it sets owner of the object C as B. After that, if the owner of B wants to receive C and do something with it, it can do so by saying it wants to receive C with this Receiving struct, and by calling the transfer::receive function along with the mutable reference to B's UID. The VM will then go and actually load C at that point and return it back for you to use in the rest of the transaction.

[tzakian]

Not done -- accidentally got closed by the landing of the main PR.

[FrankC01]

@tzakian

Are references allowed in function args (i.e. &Receiving<T>)?
If so, are mutable allowed as well (i.e. &mut Receiving<T>)?

Which would also lead me to assuming you can't use a command output as input:

...
const tx = new TransactionBlock();
const [coin] = tx.splitCoins(tx.gas,[tx.pure(1000000)]);
tx.moveCall({
  target: `${examplePackageId}::account::accept_payment`,
  arguments: [tx.object("0xcafe"), coin]
});
const result = await signer.signAndExecuteTransactionBlock({
      transactionBlock: tx,
  });
...

[tzakian]

@FrankC01

Both are allowed (so both &Receiving<T> and &mut Receiving<T>.

To your second question: you can use command output as input to functions that want Receiving arguments (the PTB layer will do the typechecking to verify the passed-in result is a Receiving type). However, importantly any Receiving<T> that will be seen during execution must have appeared in the transaction's inputs. As an example you could have Move function like something like this:

public fun pass_through<T: key>(x: Receiving<T>): Receiving<T> { x }

and this PTB would be valid:

...
const tx = new TransactionBlock();
const [recv] = tx.moveCall({
  target: `${examplePackageId}::account::pass_through`,
  arguments: [tx.object("0xc0ffee")]
});
tx.moveCall({
  target: `${examplePackageId}::account::accept_payment`,
  arguments: [tx.object("0xcafe"), recv]
});
const result = await signer.signAndExecuteTransactionBlock({
      transactionBlock: tx,
  });
...

[FrankC01]

@tzakian Good to know, thanks for confirming!

[FrankC01]

@tzakian

So I've got all manner of things tested and working:

    /// Pass through object
    public fun pass_through<T: key + store>(sent: Receiving<T>): Receiving<T> {
        sent
    }
    /// Pass through object ref - This only inspects without error but execution fails with invalid return
    public fun pass_through_ref<T: key + store>(sent: &Receiving<T>): &Receiving<T> {
        sent
    }
    /// Pass through object mutable ref - This only inspects without error but execution fails with invalid return
    public fun pass_through_mut<T: key + store>(sent: &mut Receiving<T>): &mut Receiving<T> {
        sent
    }
    /// Pass in object mutable ref
    public fun pass_in_mut_payment<T: key + store>(_sent: &mut Receiving<T>) {
    }
    /// Reference object
    public fun pass_in_ref_payment<T: key + store>(_sent: &Receiving<T>) {
    }

These are fine whether I use explicit or result of previous commend. I'm using a gas coin as T so type_argument is "0x2::coin::Coin<0x2::sui::SUI>" as Coin satisfies key + store

However, methinks your example accept_paymet is questionable as just type_argument "0x2::sui::SUI" fails the key+store constraint. Pointing this out in case it is wrong and you want to fix to prevent others scratching their heads or it is me and I'm missing something in assumptions or how things work.

[tzakian]

Great catch! Thank you for pointing it out.

This is indeed an oversight -- I'll update. The only restriction is that the type T in Receiving<T> has key. So there shouldn't need to be any restrictions on T in accept_payment since Coin<T> has key for any T.

[FrankC01]

@tzakian

That fixes the type constraint however; it is failing in inspect and/or run against devnet (1.11.0):
https://suiexplorer.com/txblock/AVxhurNcmYqP2yHoGbysGaQdGH4Cp6EbfATh6SSNj5oh?network=devnet

 "effects": {
    "status": {
      "status": "failure",
      "error": "MoveAbort(MoveLocation { module: ModuleId { address: 0000000000000000000000000000000000000000000000000000000000000002, name: Identifier(\"transfer\") }, function: 10, instruction: 0, function_name: Some(\"receive_impl\") }, 3) in command 0"
      }
} 

[tzakian]

@FrankC01

Had a look and it looks like the issue is that the object that you want to receive (https://suiexplorer.com/object/0x0f7f7288b07de5a31ac8915b503f6d7a09d05400d4a40d594d3f7a279d34050b?network=devnet) is not owned by the object you're passing as the parent (https://suiexplorer.com/object/0x7e685a1bdc34671488560ce26952bc1f57937b0e7fc465da0a6cc80740e28708?network=devnet).

You'll need to first transfer 0x0f7f7288b07de5a31ac8915b503f6d7a09d05400d4a40d594d3f7a279d34050b to 0x7e685a1bdc34671488560ce26952bc1f57937b0e7fc465da0a6cc80740e28708 and then the call to accept_payment should work.

[FrankC01]

Yep, that did it! (May want to add to example....) thanks @tzakian ... pysui now support it... with confidence!

https://suiexplorer.com/object/0x7e685a1bdc34671488560ce26952bc1f57937b0e7fc465da0a6cc80740e28708?network=devnet

[tzakian]

Amazing!

[tzakian]

Receiving object support for typescript and Rust has now been landed in main. The feature is only turned on for devnet. Trying to receive an object in testnet or mainnet will fail at the moment as the feature is not turned on for these networks.

[monday-kelvin]

hello, if I wrongly transfer a coin, like usdt or Cetus, to the sui gas object that I owned, can I retrieve the coin by using the function mentioned here?

[stefan-mysten]

I think this is now completed and available on mainnet, so we can close the issue.