gear_common/
event.rs

1// This file is part of Gear.
2
3// Copyright (C) 2021-2025 Gear Technologies Inc.
4// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
5
6// This program is free software: you can redistribute it and/or modify
7// it under the terms of the GNU General Public License as published by
8// the Free Software Foundation, either version 3 of the License, or
9// (at your option) any later version.
10
11// This program is distributed in the hope that it will be useful,
12// but WITHOUT ANY WARRANTY; without even the implied warranty of
13// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14// GNU General Public License for more details.
15
16// You should have received a copy of the GNU General Public License
17// along with this program. If not, see <https://www.gnu.org/licenses/>.
18
19//! Gear events additional data.
20//!
21//! This module contains components for depositing proper
22//! and extensive data about actions happen.
23
24use gear_core::{env::MessageWaitedType, ids::MessageId};
25use sp_runtime::{
26    codec::{self, Decode, Encode},
27    scale_info::{self, TypeInfo},
28};
29
30/// Programs entry for messages.
31///
32/// Same as `gear_core::message::DispatchKind`,
33/// but with additional info about reply.
34#[derive(Debug, Encode, Decode, Clone, PartialEq, Eq, TypeInfo)]
35#[codec(crate = codec)]
36#[scale_info(crate = scale_info)]
37pub enum MessageEntry {
38    /// Init entry point.
39    Init,
40    /// Handle entry point.
41    Handle,
42    /// Handle reply entry point.
43    Reply(MessageId),
44    /// System signal entry point.
45    Signal,
46}
47
48/// Status of dispatch dequeue and execution.
49#[derive(Debug, Encode, Decode, Clone, PartialEq, Eq, TypeInfo)]
50#[codec(crate = codec)]
51#[scale_info(crate = scale_info)]
52pub enum DispatchStatus {
53    /// Dispatch was dequeued and succeed with execution.
54    Success,
55    /// Dispatch was dequeued and failed its execution.
56    Failed,
57    /// Dispatch was dequeued and wasn't executed.
58    /// Occurs if actor no longer exists.
59    NotExecuted,
60}
61
62/// Behavior of types, which represent runtime reasons for some chain actions.
63pub trait RuntimeReason: Sized {
64    /// Converter into composite reason type: not only runtime, but system also.
65    fn into_reason<S: SystemReason>(self) -> Reason<Self, S> {
66        Reason::Runtime(self)
67    }
68}
69
70// Empty implementation for `()` to skip requirements.
71impl RuntimeReason for () {}
72
73/// Behavior of types, which represent system reasons for some chain actions.
74pub trait SystemReason: Sized {
75    /// Converter into composite reason type: not only system, but runtime also.
76    fn into_reason<R: RuntimeReason>(self) -> Reason<R, Self> {
77        Reason::System(self)
78    }
79}
80
81// Empty implementation for `()` to skip requirements.
82impl SystemReason for () {}
83
84/// Composite reason type for any action happened on chain.
85#[derive(Debug, Encode, Decode, Clone, PartialEq, Eq, TypeInfo)]
86#[codec(crate = codec)]
87#[scale_info(crate = scale_info)]
88pub enum Reason<R: RuntimeReason, S: SystemReason> {
89    /// Runtime reason variant.
90    ///
91    /// This means that actor explicitly forced some action,
92    /// which this reason explains.
93    Runtime(R),
94    /// System reason variant.
95    ///
96    /// This means that system automatically forced some action,
97    /// which this reason explains.
98    System(S),
99}
100
101/// Runtime reason for messages waiting.
102#[derive(Debug, Encode, Decode, Clone, PartialEq, Eq, TypeInfo, RuntimeReason)]
103#[codec(crate = codec)]
104#[scale_info(crate = scale_info)]
105pub enum MessageWaitedRuntimeReason {
106    /// Program called `gr_wait` while executing message.
107    WaitCalled,
108    /// Program called `gr_wait_for` while executing message.
109    WaitForCalled,
110    /// Program called `gr_wait_up_to` with insufficient gas for full
111    /// duration while executing message.
112    WaitUpToCalled,
113    /// Program called `gr_wait_up_to` with enough gas for full duration
114    /// storing while executing message.
115    WaitUpToCalledFull,
116}
117
118impl From<MessageWaitedType> for MessageWaitedRuntimeReason {
119    fn from(src: MessageWaitedType) -> Self {
120        match src {
121            MessageWaitedType::Wait => MessageWaitedRuntimeReason::WaitCalled,
122            MessageWaitedType::WaitFor => MessageWaitedRuntimeReason::WaitForCalled,
123            MessageWaitedType::WaitUpTo => MessageWaitedRuntimeReason::WaitUpToCalled,
124            MessageWaitedType::WaitUpToFull => MessageWaitedRuntimeReason::WaitUpToCalledFull,
125        }
126    }
127}
128
129/// System reason for messages waiting.
130#[derive(Debug, Encode, Decode, Clone, PartialEq, Eq, TypeInfo, SystemReason)]
131#[codec(crate = codec)]
132#[scale_info(crate = scale_info)]
133pub enum MessageWaitedSystemReason {}
134
135/// Composite reason for messages waiting.
136pub type MessageWaitedReason = Reason<MessageWaitedRuntimeReason, MessageWaitedSystemReason>;
137
138/// Runtime reason for messages waking.
139#[derive(Debug, Encode, Decode, Clone, PartialEq, Eq, TypeInfo, RuntimeReason)]
140#[codec(crate = codec)]
141#[scale_info(crate = scale_info)]
142pub enum MessageWokenRuntimeReason {
143    /// Program called `gr_wake` with corresponding message id.
144    WakeCalled,
145}
146
147/// System reason for messages waking.
148#[derive(Debug, Encode, Decode, Clone, PartialEq, Eq, TypeInfo, SystemReason)]
149#[codec(crate = codec)]
150#[scale_info(crate = scale_info)]
151pub enum MessageWokenSystemReason {
152    /// Program had finished initialization.
153    ///
154    /// Note that this variant doesn't contain info
155    /// about initialization success or failure.
156    ProgramGotInitialized,
157    /// Specified by program timeout for waking has come (see #349).
158    TimeoutHasCome,
159    /// Message can no longer pay rent for holding in storage (see #646).
160    OutOfRent,
161}
162
163/// Composite reason for messages waking.
164pub type MessageWokenReason = Reason<MessageWokenRuntimeReason, MessageWokenSystemReason>;
165
166/// Type of changes applied to code in storage.
167#[derive(Debug, Encode, Decode, Clone, PartialEq, Eq, TypeInfo)]
168#[codec(crate = codec)]
169#[scale_info(crate = scale_info)]
170pub enum CodeChangeKind<BlockNumber> {
171    /// Code become active and ready for use.
172    ///
173    /// Appear when new code created or expiration block number updated.
174    ///
175    /// Expiration block number presents block number when this code become
176    /// inactive due to losing ability to pay rent for holding.
177    /// Equals `None` if stores free (some program relays on it, see #646).
178    Active { expiration: Option<BlockNumber> },
179
180    /// Code become inactive and can no longer be used.
181    Inactive,
182
183    /// Code was reinstrumented.
184    Reinstrumented,
185}
186
187/// Runtime reason for messages reading from `Mailbox`.
188#[derive(Debug, Encode, Decode, Clone, PartialEq, Eq, TypeInfo, RuntimeReason)]
189#[codec(crate = codec)]
190#[scale_info(crate = scale_info)]
191pub enum UserMessageReadRuntimeReason {
192    /// Message was replied by user.
193    MessageReplied,
194    /// Message was claimed by user.
195    MessageClaimed,
196}
197
198/// System reason for messages reading from `Mailbox`.
199#[derive(Debug, Encode, Decode, Clone, PartialEq, Eq, TypeInfo, SystemReason)]
200#[codec(crate = codec)]
201#[scale_info(crate = scale_info)]
202pub enum UserMessageReadSystemReason {
203    /// Message can no longer pay rent for holding in storage (see #646).
204    OutOfRent,
205}
206
207/// Composite reason for messages reading from `Mailbox`.
208pub type UserMessageReadReason = Reason<UserMessageReadRuntimeReason, UserMessageReadSystemReason>;
209
210/// Type of changes applied to program in storage.
211#[derive(Debug, Encode, Decode, Clone, PartialEq, Eq, TypeInfo)]
212#[codec(crate = codec)]
213#[scale_info(crate = scale_info)]
214pub enum ProgramChangeKind<BlockNumber> {
215    /// Active status achieved.
216    ///
217    /// Occurs when new program created or paused program was resumed.
218    ///
219    /// Expiration block number presents block number when this program become
220    /// paused due to losing ability to pay rent for holding.
221    Active { expiration: BlockNumber },
222
223    /// Program become inactive forever due to `gr_exit` call.
224    Inactive,
225
226    /// Paused status.
227    ///
228    /// Program is no longer available for interaction, but can be
229    /// resumed by paying rent and giving whole data related to it.
230    Paused,
231
232    /// Program become inactive forever due to init failure.
233    Terminated,
234
235    /// Occurs when expiration block number of a program changed.
236    ///
237    /// Expiration block number presents block number when this program become
238    /// paused due to losing ability to pay rent for holding.
239    ExpirationChanged { expiration: BlockNumber },
240
241    /// Occurs when new program set in the storage.
242    ///
243    /// Expiration block number presents block number when this program become
244    /// paused due to losing ability to pay rent for holding or terminated in
245    /// case of didn't get initialised.
246    ProgramSet { expiration: BlockNumber },
247}
gear_common/event.rs

gear_common/
event.rs
