# Groups

## What are Groups?

Groups are managed collections of Items that share behaviors and supply stats, and are included as a core feature in all Marble contracts. All Marble Digital Items belong to one and only one group. 

## Supply Mechanics

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

* Creating a new Item increases the group's `supply` and `issued_supply` by 1.
* Destroying or Consuming an Item reduces the group's `supply` by 1.
* A group's `supply` of Items can never exceed the `supply_cap`.
* A group's `supply` can never be reduced below 0.

## Table Breakdown

**Table Name:** `groups`

**Table Scope:** `self`

**No Additional Indices**

| 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 Items.           |
| issued\_supply | uint64\_t  | Total lifetime issued supply of Items. |
| supply\_cap    | uint64\_t  | Max circulating supply of Items.       |

## Create a New Group

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

**Required Authority:** `admin`

### Action Parameters

| Name        | Type      | Example                  | Description                                                             |
| ----------- | --------- | ------------------------ | ----------------------------------------------------------------------- |
| title       | string    | "Test Group"             | Title of group.                                                         |
| description | string    | "Test Group for Testing" | Description of the group.                                               |
| group\_name | name      | testgroup                | The name identifier of the group.                                       |
| manager     | name      | testaccount1             | The account name of the group manager.                                  |
| supply\_cap | uint64\_t | 21000000                 | The maximum number of Items from this group that can exist at one time. |

### Examples

{% tabs %}
{% tab title="Cleos" %}

```
cleos push action {account} newgroup '[ ... ]' -p {account}
```

{% endtab %}

{% tab title="Marble CLI" %}

```
marble make group ...
```

{% endtab %}
{% endtabs %}

## Edit Group Details

Edit the group title and/or description with the `editgroup()` action.

**Required Authority:** `group.manager`

### Action Parameters

| Name             | Type   | Example                 | Description                |
| ---------------- | ------ | ----------------------- | -------------------------- |
| group\_name      | name   | testgroup               | Name of the group to edit. |
| new\_title       | string | "New Group Title"       | The new group title.       |
| new\_description | string | "New Group Description" | The new group description. |

### Examples

{% tabs %}
{% tab title="Cleos" %}

```
cleos push action {account} editgroup '[ ... ]' -p {account}
```

{% endtab %}

{% tab title="Marble CLI" %}

```
```

{% endtab %}
{% endtabs %}

## Set a New Manager

Set a new group manager with the `setmanager()` action.

**Required Authority:** `group.manager`

### Action Parameters

| Name         | Type   | Example               | Description                            |
| ------------ | ------ | --------------------- | -------------------------------------- |
| group\_name  | name   | testgroup             | Name of the group to edit.             |
| new\_manager | name   | testaccount2          | Account name of the new group manager. |
| memo         | string | "Take over from here" | Optional memo.                         |

### Examples

{% tabs %}
{% tab title="Cleos" %}

```
cleos push action {account} setmanager '[ ... ]' -p {account}
```

{% endtab %}

{% tab title="Marble CLI" %}

```
marble modify manager ...
```

{% endtab %}
{% endtabs %}