Skip to main content

Module sui::transfer

use std::ascii;
use std::bcs;
use std::option;
use std::string;
use std::vector;
use sui::address;
use sui::hex;
use sui::object;
use sui::party;
use sui::tx_context;
use sui::vec_map;

Struct Receiving​

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.

public struct Receiving<phantom T: key> has drop
Click to open
Fields
id: sui::object::ID
version: u64

Constants​

Shared an object that was previously created. Shared objects must currently be constructed in the transaction they are created.

const ESharedNonNewObject: u64 = 0;

Serialization of the object failed.

const EBCSSerializationFailure: u64 = 1;

The object being received is not of the expected type.

const EReceivingObjectTypeMismatch: u64 = 2;

Represents both the case where the object does not exist and the case where the object is not able to be accessed through the parent that is passed-in.

const EUnableToReceiveObject: u64 = 3;

Shared object operations such as wrapping, freezing, and converting to owned are not allowed.

const ESharedObjectOperationNotSupported: u64 = 4;

Operation is not yet supported by the network. The functionality might still be in development.

const ENotSupported: u64 = 5;

#[error]
const EInvalidPartyPermissions: vector<u8> = b"Party transfer is currently limited to one party.";

Function transfer​

Transfer ownership of obj to recipient. obj must have the key attribute, which (in turn) ensures that obj has a globally unique ID. Note that if the recipient address represents an object ID, the obj sent will be inaccessible after the transfer (though they will be retrievable at a future date once new features are added). This function has custom rules performed by the Sui Move bytecode verifier that ensures that T is an object defined in the module where 

transfer
is invoked. Use 
public_transfer
to transfer an object with store outside of its module.

public fun transfer<T: key>(obj: T, recipient: address)
Click to open
Implementation
public fun transfer<T: key>(obj: T, recipient: address) {
    transfer_impl(obj, recipient)
}

Function public_transfer​

Transfer ownership of obj to recipient. obj must have the key attribute, which (in turn) ensures that obj has a globally unique ID. Note that if the recipient address represents an object ID, the obj sent will be inaccessible after the transfer (though they will be retrievable at a future date once new features are added). The object must have store to be transferred outside of its module.

public fun public_transfer<T: key, store>(obj: T, recipient: address)
Click to open
Implementation
public fun public_transfer<T: key + store>(obj: T, recipient: address) {
    transfer_impl(obj, recipient)
}

Function party_transfer​

NOT YET SUPPORTED ON MAINNET. The function will abort with 

ENotSupported
if used on a network where party objects are not yet supported. Transfer ownership of obj to the 
party
. This transfer behaves similar to both 
transfer
and 
share_object
. It is similar to 
transfer
in that the object is authorized for use only by the recipient(s), in this case the 
party
. This means that only the members can use the object as an input to a transaction. It is similar to 
share_object
two ways. One in that the object can potentially be used by anyone, as defined by the default permissions of the Party value. The other in that the object must be used in consensus and cannot be used in the fast path. This function has custom rules performed by the Sui Move bytecode verifier that ensures that T is an object defined in the module where 
transfer
is invoked. Use 
public_party_transfer
to transfer an object with store outside of its module.

public fun party_transfer<T: key>(obj: T, party: sui::party::Party)
Click to open
Implementation
public fun party_transfer<T: key>(obj: T, party: sui::party::Party) {
    assert!(party.is_single_owner(), EInvalidPartyPermissions);
    let (default, addresses, permissions) = party.into_native();
    party_transfer_impl(obj, default, addresses, permissions)
}

Function public_party_transfer​

NOT YET SUPPORTED ON MAINNET. The function will abort with 

ENotSupported
if used on a network where party objects are not yet supported. Transfer ownership of obj to the 
party
. This transfer behaves similar to both 
transfer
and 
share_object
. It is similar to 
transfer
in that the object is authorized for use only by the recipient(s), in this case the 
party
. This means that only the members can use the object as an input to a transaction. It is similar to 
share_object
two ways. One in that the object can potentially be used by anyone, as defined by the default permissions of the Party value. The other in that the object must be used in consensus and cannot be used in the fast path. The object must have store to be transferred outside of its module.

public fun public_party_transfer<T: key, store>(obj: T, party: sui::party::Party)
Click to open
Implementation
public fun public_party_transfer<T: key + store>(obj: T, party: sui::party::Party) {
    assert!(party.is_single_owner(), EInvalidPartyPermissions);
    let (default, addresses, permissions) = party.into_native();
    party_transfer_impl(obj, default, addresses, permissions)
}

Function freeze_object​

Freeze obj. After freezing obj becomes immutable and can no longer be transferred or mutated. This function has custom rules performed by the Sui Move bytecode verifier that ensures that T is an object defined in the module where 

freeze_object
is invoked. Use 
public_freeze_object
to freeze an object with store outside of its module.

public fun freeze_object<T: key>(obj: T)
Click to open
Implementation
public fun freeze_object<T: key>(obj: T) {
    freeze_object_impl(obj)
}

Function public_freeze_object​

Freeze obj. After freezing obj becomes immutable and can no longer be transferred or mutated. The object must have store to be frozen outside of its module.

public fun public_freeze_object<T: key, store>(obj: T)
Click to open
Implementation
public fun public_freeze_object<T: key + store>(obj: T) {
    freeze_object_impl(obj)
}

Function share_object​

Turn the given object into a mutable shared object that everyone can access and mutate. This is irreversible, i.e. once an object is shared, it will stay shared forever. Aborts with 

ESharedNonNewObject
of the object being shared was not created in this transaction. This restriction may be relaxed in the future. This function has custom rules performed by the Sui Move bytecode verifier that ensures that T is an object defined in the module where 
share_object
is invoked. Use 
public_share_object
to share an object with store outside of its module.

public fun share_object<T: key>(obj: T)
Click to open
Implementation
public fun share_object<T: key>(obj: T) {
    share_object_impl(obj)
}

Function public_share_object​

Turn the given object into a mutable shared object that everyone can access and mutate. This is irreversible, i.e. once an object is shared, it will stay shared forever. Aborts with 

ESharedNonNewObject
of the object being shared was not created in this transaction. This restriction may be relaxed in the future. The object must have store to be shared outside of its module.

public fun public_share_object<T: key, store>(obj: T)
Click to open
Implementation
public fun public_share_object<T: key + store>(obj: T) {
    share_object_impl(obj)
}

Function receive​

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. This function has custom rules performed by the Sui Move bytecode verifier that ensures that T is an object defined in the module where 
receive
is invoked. Use 
public_receive
to receivne an object with store outside of its module.

public fun receive<T: key>(parent: &mut sui::object::UID, to_receive: sui::transfer::Receiving<T>): T
Click to open
Implementation
public fun receive<T: key>(parent: &mut UID, to_receive: Receiving<T>): T {
    let Receiving { id, version } = to_receive;
    receive_impl(parent.to_address(), id, version)
}

Function public_receive​

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. The object must have store to be received outside of its defining module.

public fun public_receive<T: key, store>(parent: &mut sui::object::UID, to_receive: sui::transfer::Receiving<T>): T
Click to open
Implementation
public fun public_receive<T: key + store>(parent: &mut UID, to_receive: Receiving<T>): T {
    let Receiving { id, version } = to_receive;
    receive_impl(parent.to_address(), id, version)
}

Function receiving_object_id​

Return the object ID that the given 

Receiving
argument references.

public fun receiving_object_id<T: key>(receiving: &sui::transfer::Receiving<T>): sui::object::ID
Click to open
Implementation
public fun receiving_object_id<T: key>(receiving: &Receiving<T>): ID {
    receiving.id
}

Function freeze_object_impl​

public(package) fun freeze_object_impl<T: key>(obj: T)
Click to open
Implementation
public(package) native fun freeze_object_impl<T: key>(obj: T);

Function share_object_impl​

public(package) fun share_object_impl<T: key>(obj: T)
Click to open
Implementation
public(package) native fun share_object_impl<T: key>(obj: T);

Function party_transfer_impl​

public(package) fun party_transfer_impl<T: key>(obj: T, default_permissions: u64, addresses: vector<address>, permissions: vector<u64>)
Click to open
Implementation
public(package) native fun party_transfer_impl<T: key>(
    obj: T,
    default_permissions: u64,
    addresses: vector<address>,
    permissions: vector<u64>,
);

Function transfer_impl​

public(package) fun transfer_impl<T: key>(obj: T, recipient: address)
Click to open
Implementation
public(package) native fun transfer_impl<T: key>(obj: T, recipient: address);

Function receive_impl​

fun receive_impl<T: key>(parent: address, to_receive: sui::object::ID, version: u64): T
Click to open
Implementation
native fun receive_impl<T: key>(parent: address, to_receive: ID, version: u64): T;