Skip to main content

Events

Events are generated for certain operations during execution. The following sections describe events that are part of the default Gear Protocol's runtime.

To subscribe to all events:

const unsub = await api.query.system.events((events) => {
console.log(events.toHuman());
});
// Unsubscribe
unsub();

Events Types

MessageQueued

Summary: When a user successfully sends a message to a program and it gets added to the message queue.


MessageQueued {
/// Generated id of the message.
id: MessageId,
/// Account id of the source of the message.
source: T::AccountId,
/// Program id, who is the message's destination.
destination: ProgramId,
/// Entry point for processing of the message.
/// On the sending stage, the processing function
/// of the program is always known.
entry: MessageEntry,
}

UserMessageSent

Summary: When someone has sent a message to the user.

UserMessageSent {
/// Message sent.
message: UserMessage,
/// Block number of expiration from `Mailbox`.
///
/// Equals `Some(_)` with block number when message
/// will be removed from `Mailbox` due to some
/// reasons (see #642, #646 and #1010).
///
/// Equals `None` if message wasn't inserted to
/// `Mailbox` and appears as only `Event`.
expiration: Option<T::BlockNumber>,
}

UserMessageRead

Summary: When a message has been marked as "read" and it has been removed from the Mailbox. This event only affects messages, which were already prior inserted into the Mailbox.

UserMessageRead {
/// Id of the message read.
id: MessageId,
/// The reason for the reading (removal from `Mailbox`).
///
/// NOTE: See more docs about reasons at `gear_common::event`.
reason: UserMessageReadReason,
}

MessagesDispatched

Summary: The result of when a message is processed within the block.

MessagesDispatched {
/// Total amount of messages removed from message queue.
total: MessengerCapacityOf<T>,
/// Execution statuses of the messages, which were already known
/// by `Event::MessageQueued` (sent from user to program).
statuses: BTreeMap<MessageId, DispatchStatus>,
/// Ids of programs, which state changed during queue processing.
state_changes: BTreeSet<ProgramId>,
}

MessageWaited

Summary: When a message's execution has been delayed and it has been added to the waitlist.

MessageWaited {
/// Id of the message waited.
id: MessageId,
/// Origin message id, which started messaging chain with programs,
/// where currently waited message was created.
///
/// Used to identify by the user that this message associated
/// with him and the concrete initial message.
origin: Option<GasNodeId<MessageId, ReservationId>>,
/// The reason of the waiting (addition to `Waitlist`).
///
/// NOTE: See more docs about reasons at `gear_common::event`.
reason: MessageWaitedReason,
/// Block number of expiration from `Waitlist`.
///
/// Equals block number when message will be removed from `Waitlist`
/// due to some reasons (see #642, #646 and #1010).
expiration: T::BlockNumber,
}

MessageWoken

Summary: When a message is ready to continue its execution and has been removed from the Waitlist.

MessageWoken {
/// Id of the message woken.
id: MessageId,
/// The reason of the waking (removal from `Waitlist`).
///
/// NOTE: See more docs about reasons at `gear_common::event`.
reason: MessageWokenReason,
}

CodeChanged

Summary: When a program's code has been altered.

CodeChanged {
/// Id of the code affected.
id: CodeId,
/// Change applied on code with current id.
///
/// NOTE: See more docs about change kinds at `gear_common::event`.
change: CodeChangeKind<T::BlockNumber>,
}

ProgramChanged

Summary: Any data related to program changed.

ProgramChanged {
/// Id of the program affected.
id: ProgramId,
/// Change applied on program with current id.
///
/// NOTE: See more docs about change kinds at `gear_common::event`.
change: ProgramChangeKind<T::BlockNumber>,
}

ProgramResumeSessionStarted

Summary: Program resume session has been started.

ProgramResumeSessionStarted {
/// Id of the session.
session_id: SessionId,
/// Owner of the session.
account_id: T::AccountId,
/// Id of the program affected.
program_id: ProgramId,
/// Block number when the session will be removed if not finished.
session_end_block: T::BlockNumber
}

Check what the event is

api.query.system.events((events) => {
events
.filter(({ event }) => api.events.gear.MessageQueued.is(event))
.forEach(({ event: { data } }) => {
console.log(data.toHuman());
});

events
.filter(({ event }) => api.events.balances.Transfer.is(event))
.forEach(({ event: { data } }) => {
console.log(data.toHuman());
});
});

Subscribe to specific events

Subscribe to messages sent from a program

const unsub = api.gearEvents.subscribeToGearEvent(
'UserMessageSent',
({
data: {
message: { id, source, destination, payload, value, reply },
},
}) => {
console.log(`
messageId: ${id.toHex()}
source: ${source.toHex()}
payload: ${payload.toHuman()}
`);
},
);
// Unsubscribe
unsub();

Subscribe to messages intended for a program

const unsub = api.gearEvents.subscribeToGearEvent(
'MessageQueued',
({ data: { id, source, destination, entry } }) => {
console.log({
messageId: id.toHex(),
programId: destination.toHex(),
userId: source.toHex(),
entry: entry.isInit
? entry.asInit
: entry.isHandle
? entry.asHandle
: entry.asReply,
});
},
);
// Unsubscribe
unsub();

Subscribe to Transfer events

const unsub = await api.gearEvents.subscribeToTransferEvents(
({ data: { from, to, amount } }) => {
console.log(`
Transfer balance:
from: ${from.toHex()}
to: ${to.toHex()}
amount: ${+amount.toString()}
`);
},
);
// Unsubscribe
unsub();

Subscribe to new blocks

const unsub = await api.gearEvents.subscribeToNewBlocks((header) => {
console.log(
`New block with number: ${header.number.toNumber()} and hash: ${header.hash.toHex()}`,
);
});
// Unsubscribe
unsub();