Groups

What are Groups?

Groups are managed collections of NFTs that share behaviors. All Marble NFTs belong to one and only one group. Marble includes Groups as a core feature included in all Marble contracts.

Group Behaviors

The following behaviors are created for every group by default. Group behaviors apply to all the NFTs in a given group, and behaviors can be added, removed, or toggled on and off by the group manager.

Behavior Name

Default Value

Description

mintable

true

Allows NFTs to be minted with the newnft() action.

transferable

true

Allows NFT ownership to be transferred with both the transfernft() and transfernfts() actions.

destructible

true

Allows NFTS to be destroyed with the destroynft() action.

taggable

true

Allows NFTs to be tagged with the newtag() action.

updateable

true

Allows tags to be updated with the updatetag() action.

attributable

true

Allows NFTs to be assigned attributes with the newattribute() action.

increasable

true

Allows attribute points to be increased with the increasepts() action.

decreasable

true

Allows attribute points to. be decreased with the decreasepts() action.

Supply Mechanics

Marble automatically enforces supply control mechanics into NFT creation and destruction. The mechanical rules are as follows:

  • Creating a new NFT increases the group's supply and issued_supply by 1.

  • Destroying an NFT reduces the group's supply by 1.

  • A group's supply of NFTs can never exceed the supply_cap.

  • A group's supply can never be reduced below 0.

Table Breakdown

Table Name: groups

Table Scope: self

Field Name

Field Type

Description

title

string

Group title.

subtitle

string

Group subtitle.

group_name

name

Name Identifier (Primary Key).

manager

name

Account assigned as group manager.

supply

uint64_t

Circulating supply of NFTs.

issued_supply

uint64_t

Total lifetime issued supply of NFTs.

supply_cap

uint64_t

Max circulating supply of NFTs.

behaviors

map<name, bool>

Map of behavior names and on/off states.

No extra indices.

Create a Group

To create a new group, simply call the newgroup() action on your Marble contract.

Required Authority: admin

Action Parameters

  • string title: The title of the Group.

  • string description: A short tweet-length description of the Group.

  • name group_name: The eosio::name identifier of the group.

  • name manager: The account that manages Group behaviors and can mint and destroy NFTs.

  • uint64_t supply_cap: The maximum number of NFTs from this group that can exist at one time.

Examples

Cleos
Marble CLI
Cleos
cleos push action {account} newgroup '[ {params} ]' -p {account}
Marble CLI
marble make group ...

Toggle Behavior

The toggle() action toggles group-wide NFT behaviors on and off.

Required Authority: group.manager

Action Parameters

  • name group_name: Group with behavior to toggle.

  • name behavior_name: Behavior to toggle.

  • string memo: Memo explaining reason for toggling.

Examples

Cleos
Marble CLI
Cleos
cleos push action {account} toggle '[ {params} ]' -p {account}
Marble CLI
marble modify toggle ...

Add New Behavior

New behaviors can be added to a group with the addbehavior() action.

Required Authority: group.manager

Action Parameters

  • name group_name: The name of the Group to add the behavior.

  • name behavior_name: The name of the new behavior.

  • bool initial_value: The initial state of the behavior.

Examples

Cleos
Marble CLI
Cleos
cleos push action {account} addbehavior '[ {params} ]' -p {account}
Marble CLI
marble modify addbehavior

Remove Behavior

Behaviors can be removed from a group by calling the rmvbehavior() action.

Required Authority: group.manager

Action Parameters

  • name group_name: The name of the group with the behavior to remove.

  • name behavior_name: The name of the behavior to remove.

Examples

Cleos
Marble CLI
Cleos
cleos push action {account} rmvbehavior '[ {params} ]' -p {account}
Marble CLI
marble remove behavior ...

Set New Manager

To set a new group manager, send a setmanager() action to your Marble contract.

Required Authority: group.manager

Action Parameters

  • name group_name: The name of the group to change.

  • name new_manager: The name of the new new group manager.

  • string memo: An optional memo field.

Examples

Cleos
Marble CLI
Cleos
cleos push action {account} setmanager '[ {params} ]' -p {account}
Marble CLI
marble modify manager ...

‚Äč