# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://craig-branscom.gitbook.io/marble-docs/contract-standard/marble-core/groups.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.