0x0::collection

Module defining the OriginByte Collection and MintCap types

Conceptually, we can think of NFTs as being organized into collections; a one-to-many relational data model.

OriginByte collections serve two purposes, to centralise collection level information on one object and thus avoid redundancy, and to provide configuration data to NFTs.

Structs

collection::Collection<C> has store, key

    
    

        
Fields:



    
        

            Name
            Type
            Description
        

    
    

    
        id
    
    
        object::UID
    
    
Collection ID






        
NFT Collection object


OriginByte collections and NFTs have a generic parameter C which is a
one-time witness created by the creator's NFT collection module. This
allows Collection and Nft to be linked via type association, but
also ensures that NFTs can only be minted by the contract that
initially deployed them.


A Collection, like each Nft, exclusively owns domains of different
types, which can be dynamically acquired and lost over its lifetime.
OriginByte collections are modelled after
Entity Component Systems,
where their domains are accessible by type. See
borrow_domain_mut.


    



    
        
collection::MintCollectionEvent has copy, drop

    
    

        
Fields:



    
        

            Name
            Type
            Description
        

    
    

    
        collection_id
    
    
        object::ID
    
    
ID of the Collection that was minted




    
        type_name
    
    
        type_name::TypeName
    
    
Type name of Collection<C> one-time witness C


Intended to allow users to filter by collections of interest.






        
Event signalling that a Collection was minted


    



    
Methods

    

    
        
public fun create<C>(
    _witness: &C,
    ctx: &mut tx_context::TxContext,
): (mint_cap::MintCap<C>, collection::Collection<C>)

    
    
Creates a Collection<C> and corresponding MintCap<C>


Usage


struct FOOTBALL has drop {}

fun init(witness: FOOTBALL, ctx: &mut TxContext) {
    let (mint_cap, collection) = collection::create(&witness, ctx);
}






    
        
public fun init_collection<C>(
    witness: &C,
    owner: address,
    ctx: &mut tx_context::TxContext,
)

    
    
Creates a shared Collection<C> and corresponding MintCap<C>





    
        
public fun has_domain<C, D: store>(
    collection: &collection::Collection<C>,
): bool

    
    
Check whether Collection has a domain of type D





    
        
public fun borrow_domain<C, D: store>(
    collection: &collection::Collection<C>,
): &D

    
    
Borrow domain of type D from Nft


Panics


Panics if domain of type D is not present on the Nft





    
        
public fun borrow_domain_mut<C, D: store, W: drop>(
    _witness: W,
    collection: &mut collection::Collection<C>,
): &mut D

    
    
Mutably borrow domain of type D from Collection


Guarantees that domain D can only be mutated by the module that
instantiated it. In other words, witness W must be defined in the
same module as domain D.


Usage


module nft_protocol::display {
    struct SUIMARINES has drop {}
    struct Witness has drop {}

    struct DisplayDomain {
        id: UID,
        name: String,
    } has key, store

    public fun domain_mut(collection: &mut Collection<C>): &mut DisplayDomain {
        let domain: &mut DisplayDomain =
            collection::borrow_domain_mut(Witness {}, collection);
    }
}



Panics


Panics when module attempts to mutably borrow a domain it did not
define itself or if domain of type D is not present on the Nft. See
nft::borrow_domain_mut.







    
        
public fun add_domain<C, W, D: store>(
    witness: &W,
    collection: &mut collection::Collection<C>,
    domain: D,
)

    
    
Adds domain of type D to Collection


Helper method that can be simply used without knowing what a delegated
witness is.


Panics


Panics if domain D already exists.





    
        
public fun add_domain_delegated<C, D: store>(
    _witness: witness::Witness<C>,
    collection: &mut collection::Collection<C>,
    domain: D,
)

    
    
Adds domain of type D to Collection


Panics


Panics if domain D already exists.





    
        
public fun remove_domain<C, W: drop, D: store>(
    _witness: W,
    collection: &mut collection::Collection<C>,
): D

    
    
Removes domain of type D from Collection


Panics


Panics when module attempts to remove a domain it did not define
itself or if domain of type D is not present on the Collection. See
borrow_domain_mut.


Usage


let display_domain: DisplayDomain = collection::remove_domain(Witness {}, &mut nft);






    
        
public fun assert_domain<C, D: store>(
    collection: &collection::Collection<C>,
)

    
    
Assert that domain D exists on Collection


Panics


Panics if domain, D, does not exist on Collection.





    
        
public fun assert_no_domain<C, D: store>(
    collection: &collection::Collection<C>,
)

    
    
Assert that domain D does not exist on Collection


Panics


Panics if domain, D, does exists on Collection.