# Items

## What are Digital Items?

Digital Items are individual, ownable objects stored by the Marble contract. A Digital Item can represent anything from a trading card to a deed of ownership to an in-game spaceship. 

Upon creation, every Item is given a unique contract-wide serial number used to identify it among all other Items in the contract. 

Ownership of an Item can be proven by controlling the account that owns a given Item. Every Item also belongs to one and only one Group, which dictates the different kinds of behaviors the Item can perform.

## Behavior Rules

Items follow the behavior rules set by their respective groups. For example, if an Item belongs to a group whose `transfer` behavior is set to false, then the Item is not transferrable. If the group manager were to activate transferability with the `toggle()` action, the Item would become transferrable. See the Behaviors section for more information on behaviors.

## Table Breakdown

**Table Name:** `items`

**Table Scope:** `self`

| Field Name | Field Type | Description                                     |
| ---------- | ---------- | ----------------------------------------------- |
| serial     | uint64\_t  | Contract-wide Item serial number. (Primary Key) |
| group      | name       | Group name identifier.                          |
| owner      | name       | Account that owns the Item.                     |

#### Additional Indices

`bygroup`, `byowner`

## Mint New Item

To create a new Item, call the `mintitem()` action on your Marble contract.

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

### Action Parameters

| Name  | Type | Example      | Description                                       |
| ----- | ---- | ------------ | ------------------------------------------------- |
| to    | name | testaccount1 | The recipient account that will own the new Item. |
| group | name | group1       | The group the new Item will belong to.            |

### Examples

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

```
cleos push action {account} mintitem '[ {params} ]' -p {manager}
```

{% endtab %}

{% tab title="Marble CLI" %}

```
marble make item ...
```

{% endtab %}
{% endtabs %}

## Transfer an Item

To transfer an Item, call the `transferitem(`) action on your Marble contract.

{% hint style="warning" %}
All items included in the transfer must be owned by the "from" account to be a valid transfer.
{% endhint %}

**Required Authority:** `item.owner`

**Notified Accounts:** `from`, `to`

### Action Parameters

| Name    | Type               | Example       | Description                                  |
| ------- | ------------------ | ------------- | -------------------------------------------- |
| from    | name               | testaccount1  | Account name of sender.                      |
| to      | name               | testaccount2  | Account name of recipient.                   |
| serials | vector\<uint64\_t> | \[5, 6, 8, 9] | The serial numbers of the Items to transfer. |
| memo    | string             | "Thank You!"  | An optional memo field.                      |

### Examples

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

```
cleos push action {account} transferitem '[ {params} ]' -p {owner}
```

{% endtab %}

{% tab title="Marble CLI" %}

```
marble item transfer ...
```

{% endtab %}
{% endtabs %}

## Activate an Item

Items can be activated with the `activateitem()` action. Developers can interpret what activations do in reference to their own applications. Items can be activated any number of times.

**Required Authority:** `item.owner` and `group.manager`

### Action Parameters

| Name   | Type      | Example | Description                            |
| ------ | --------- | ------- | -------------------------------------- |
| serial | uint64\_t | 5       | Serial number of the Item to activate. |

### Examples

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

```
cleos push action {account} activateitem '[ {params} ]'
```

{% endtab %}

{% tab title="Marble CLI" %}

```
marble item activate ...
```

{% endtab %}
{% endtabs %}

## Consume an Item

Some Items can be consumed by the owner. Consumable Items will be destroyed after consumption. Developers determine what Item consumption translates to in their projects.

**Required Authority**: `item.owner`

### Action Parameters

| Name   | Type      | Example | Description                           |
| ------ | --------- | ------- | ------------------------------------- |
| serial | uint64\_t | 5       | Serial number of the Item to consume. |

### Examples

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

```
cleos push action {account} consumeitem '[ {params} ]' -p {owner}
```

{% endtab %}

{% tab title="Marble CLI" %}

```
marble item consume
```

{% endtab %}
{% endtabs %}

## Destroy an Item

&#x20;To destroy an Item, call the `destroyitem()` action on your Marble contract.

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

### Action Parameters

| Name   | Type      | Example             | Description                       |
| ------ | --------- | ------------------- | --------------------------------- |
| serial | uint64\_t | 5                   | Serial number of Item to destroy. |
| memo   | string    | "Destroying Item 5" | Optional memo                     |

### Examples

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

```
cleos push action {account} destroyitem '[ {params} ]' -p {manager}
```

{% endtab %}

{% tab title="Marble CLI" %}

```
marble item destroy ...
```

{% endtab %}
{% endtabs %}