Events

Updated: 2022/1/21 by

2 min read

Events are special values that can be emitted during the execution of a program.

An event type can be declared with the event keyword.

1
event FooEvent(x: Int, y: Int)

The syntax of an event declaration is similar to that of a function declaration; events contain named parameters, each of which has an optional argument label.

Event parameters may only have a valid event parameter type. Valid types are boolean, string, integer, arrays and dictionaries of these types, and structures where all fields have a valid event parameter type. Resource types are not allowed, because when a resource is used as an argument, it is moved.

Events can only be declared within a contract body. Events cannot be declared globally or within resource or struct types.

1
// Invalid: An event cannot be declared globally
2
//
3
event GlobalEvent(field: Int)
4

5
pub contract Events {
6
    // Event with explicit argument labels
7
    //
8
    event BarEvent(labelA fieldA: Int, labelB fieldB: Int)
9

10
    // Invalid: A resource type is not allowed to be used
11
    // because it would be moved and lost
12
    //
13
    event ResourceEvent(resourceField: @Vault)
14
}

Emitting events

To emit an event from a program, use the emit statement:

1
pub contract Events {
2
    event FooEvent(x: Int, y: Int)
3

4
    // Event with argument labels
5
    event BarEvent(labelA fieldA: Int, labelB fieldB: Int)
6

7
    fun events() {
8
        emit FooEvent(x: 1, y: 2)
9

10
        // Emit event with explicit argument labels
11
        // Note that the emitted event will only contain the field names,
12
        // not the argument labels used at the invocation site.
13
        emit BarEvent(labelA: 1, labelB: 2)
14
    }
15
}

Emitting events has the following restrictions:

Events can only be invoked in an emit statement.

This means events cannot be assigned to variables or used as function parameters.
Events can only be emitted from the location in which they are declared.