# Events

## What is an Event?

The Events Layer adds the ability to attach timestamps to individual Items. Events can be set for any time point and can be used by other features as a method for storing custom time points.

## Shared Events

The Events layer also provides the Shared Events table for storing group-wide events. Set the shared flag to true on a given Event Action to specify a shared event.

## Table Breakdown

**Table Name:** `events`

**Table Scope:** `item.serial`

| Name        | Type             | Example             | Description                    |
| ----------- | ---------------- | ------------------- | ------------------------------ |
| event\_name | name             | createtime          | The name of the event.         |
| event\_time | time\_point\_sec | 2020-05-30T10:58:05 | The time of the event.         |
| locked      | bool             | false               | The locked state of the event. |

## Create a New Event

Create a new Event with the `newevent()` action.

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

### Action Parameters

| Name                | Type                        | Example             | Description                                        |
| ------------------- | --------------------------- | ------------------- | -------------------------------------------------- |
| serial              | uint64\_t                   | 5                   | The serial number of the Item to assign the event. |
| event\_name         | name                        | minttime            | The name of the event.                             |
| custom\_event\_time | optional\<time\_point\_sec> | 2020-05-30T10:58:05 | The custom event time to set for the event.        |
| shared              | bool                        | true                | Create shared event if true.                       |

### Examples

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

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

{% endtab %}

{% tab title="Marble CLI" %}

```
marble event ...
```

{% endtab %}
{% endtabs %}

## Update an Event Time

Update an event timestamp with the `seteventtime()` action.

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

### Action Parameters

| Name             | Type             | Example             | Description                              |
| ---------------- | ---------------- | ------------------- | ---------------------------------------- |
| serial           | uint64\_t        | 5                   | The serial number of the Item to affect. |
| event\_name      | name             | cooldown            | The name of the event to affect.         |
| new\_event\_time | time\_point\_sec | 2020-05-30T10:58:05 | The new event time to set for the event. |
| shared           | bool             | true                | Update shared event if true.             |

### Examples

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

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

{% endtab %}

{% tab title="Marble CLI" %}

```
marble update ...
```

{% endtab %}
{% endtabs %}

## Lock an Event

Lock an event with the `lockevent()` action.

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

### Action Parameters

| Name        | Type      | Example  | Description                                           |
| ----------- | --------- | -------- | ----------------------------------------------------- |
| serial      | uint64\_t | 5        | The serial number of the Item with the event to lock. |
| event\_name | name      | cooldown | The name of the event to lock.                        |
| shared      | bool      | false    | Lock a shared event if true.                          |

### Examples

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

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

{% endtab %}

{% tab title="Marble CLI" %}

```
marble lock ...
```

{% endtab %}
{% endtabs %}

## Remove an Event

Remove an event with the `rmvevent()` action.

Required Authority: group.manager

### Action Parameters

| Name        | Type      | Example  | Description                                             |
| ----------- | --------- | -------- | ------------------------------------------------------- |
| serial      | uint64\_t | 5        | The serial number of the Item with the event to remove. |
| event\_name | name      | cooldown | The name of the event to remove.                        |
| shared      | bool      | true     | Remove a shared event if true.                          |

### Examples

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

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

{% endtab %}

{% tab title="Marble CLI" %}

```
marble event ...
```

{% endtab %}
{% endtabs %}