iota_types/
messages_grpc.rs

1// Copyright (c) Mysten Labs, Inc.
2// Modifications Copyright (c) 2024 IOTA Stiftung
3// SPDX-License-Identifier: Apache-2.0
4
5use iota_sdk_types::ObjectId;
6use move_core_types::annotated_value::MoveStructLayout;
7use serde::{Deserialize, Serialize};
8
9use crate::{
10    base_types::{SequenceNumber, TransactionDigest},
11    crypto::{AuthoritySignInfo, AuthorityStrongQuorumSignInfo},
12    effects::{SignedTransactionEffects, TransactionEvents, VerifiedSignedTransactionEffects},
13    messages_consensus::SignedAuthorityCapabilitiesV1,
14    object::Object,
15    transaction::{CertifiedTransaction, SenderSignedData, SignedTransaction},
16};
17
18#[derive(Debug, PartialEq, Eq, Hash, Clone, Serialize, Deserialize)]
19pub enum ObjectInfoRequestKind {
20    /// Request the latest object state.
21    LatestObjectInfo,
22    /// Request a specific version of the object.
23    /// This is used only for debugging purpose and will not work as a generic
24    /// solution since we don't keep around all historic object versions.
25    /// No production code should depend on this kind.
26    PastObjectInfoDebug(SequenceNumber),
27}
28
29/// Layout generation options -- you can either generate or not generate the
30/// layout.
31#[derive(Debug, PartialEq, Eq, Hash, Clone, Serialize, Deserialize)]
32pub enum LayoutGenerationOption {
33    Generate,
34    None,
35}
36
37/// A request for information about an object and optionally its
38/// parent certificate at a specific version.
39#[derive(Debug, PartialEq, Eq, Hash, Clone, Serialize, Deserialize)]
40pub struct ObjectInfoRequest {
41    /// The id of the object to retrieve, at the latest version.
42    pub object_id: ObjectId,
43    /// if true return the layout of the object.
44    pub generate_layout: LayoutGenerationOption,
45    /// The type of request, either latest object info or the past.
46    pub request_kind: ObjectInfoRequestKind,
47}
48
49impl ObjectInfoRequest {
50    pub fn past_object_info_debug_request(
51        object_id: ObjectId,
52        version: SequenceNumber,
53        generate_layout: LayoutGenerationOption,
54    ) -> Self {
55        ObjectInfoRequest {
56            object_id,
57            generate_layout,
58            request_kind: ObjectInfoRequestKind::PastObjectInfoDebug(version),
59        }
60    }
61
62    pub fn latest_object_info_request(
63        object_id: ObjectId,
64        generate_layout: LayoutGenerationOption,
65    ) -> Self {
66        ObjectInfoRequest {
67            object_id,
68            generate_layout,
69            request_kind: ObjectInfoRequestKind::LatestObjectInfo,
70        }
71    }
72}
73
74/// This message provides information about the latest object and its lock.
75#[derive(Debug, Clone, Serialize, Deserialize)]
76pub struct ObjectInfoResponse {
77    /// Value of the requested object in this authority
78    pub object: Object,
79    /// Schema of the Move value inside this object.
80    /// None if the object is a Move package, or the request did not ask for the
81    /// layout
82    pub layout: Option<MoveStructLayout>,
83    /// Transaction the object is locked on in this authority.
84    /// None if the object is not currently locked by this authority.
85    /// This should be only used for debugging purpose, such as from iota-tool.
86    /// No prod clients should rely on it.
87    pub lock_for_debugging: Option<SignedTransaction>,
88}
89
90/// Verified version of `ObjectInfoResponse`. `layout` and `lock_for_debugging`
91/// are skipped because they are not needed and we don't want to verify them.
92#[derive(Debug, Clone)]
93pub struct VerifiedObjectInfoResponse {
94    /// Value of the requested object in this authority
95    pub object: Object,
96}
97
98#[derive(Clone, Debug, Serialize, Deserialize)]
99pub struct TransactionInfoRequest {
100    pub transaction_digest: TransactionDigest,
101}
102
103#[expect(clippy::large_enum_variant)]
104#[derive(Clone, Debug, Serialize, Deserialize)]
105pub enum TransactionStatus {
106    /// Signature over the transaction.
107    Signed(AuthoritySignInfo),
108    /// For executed transaction, we could return an optional certificate
109    /// signature on the transaction (i.e. the signature part of the
110    /// CertifiedTransaction), as well as the signed effects.
111    /// The certificate signature is optional because for transactions executed
112    /// in previous epochs, we won't keep around the certificate signatures.
113    Executed(
114        Option<AuthorityStrongQuorumSignInfo>,
115        SignedTransactionEffects,
116        TransactionEvents,
117    ),
118}
119
120impl TransactionStatus {
121    pub fn into_signed_for_testing(self) -> AuthoritySignInfo {
122        match self {
123            Self::Signed(s) => s,
124            _ => unreachable!("Incorrect response type"),
125        }
126    }
127
128    pub fn into_effects_for_testing(self) -> SignedTransactionEffects {
129        match self {
130            Self::Executed(_, e, _) => e,
131            _ => unreachable!("Incorrect response type"),
132        }
133    }
134}
135
136impl PartialEq for TransactionStatus {
137    fn eq(&self, other: &Self) -> bool {
138        match self {
139            Self::Signed(s1) => match other {
140                Self::Signed(s2) => s1.epoch == s2.epoch,
141                _ => false,
142            },
143            Self::Executed(c1, e1, ev1) => match other {
144                Self::Executed(c2, e2, ev2) => {
145                    c1.as_ref().map(|a| a.epoch) == c2.as_ref().map(|a| a.epoch)
146                        && e1.epoch() == e2.epoch()
147                        && e1.digest() == e2.digest()
148                        && ev1.digest() == ev2.digest()
149                }
150                _ => false,
151            },
152        }
153    }
154}
155
156#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
157pub struct HandleTransactionResponse {
158    pub status: TransactionStatus,
159}
160
161#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
162pub struct TransactionInfoResponse {
163    pub transaction: SenderSignedData,
164    pub status: TransactionStatus,
165}
166
167#[derive(Clone, Debug, Serialize, Deserialize)]
168pub struct SubmitCertificateResponse {
169    /// If transaction is already executed, return same result as
170    /// handle_certificate
171    pub executed: Option<HandleCertificateResponseV1>,
172}
173
174#[derive(Clone, Debug)]
175pub struct VerifiedHandleCertificateResponse {
176    pub signed_effects: VerifiedSignedTransactionEffects,
177    pub events: TransactionEvents,
178}
179
180#[derive(Serialize, Deserialize, Clone, Debug)]
181pub struct SystemStateRequest {
182    // This is needed to make gRPC happy.
183    pub _unused: bool,
184}
185
186/// Response type for version 1 of the handle certificate validator API.
187///
188/// The corresponding version 1 request type allows for a client to request
189/// events as well as input/output objects from a transaction's execution. Given
190/// Validators operate with very aggressive object pruning, the return of
191/// input/output objects is only done immediately after the transaction has been
192/// executed locally on the validator and will not be returned for requests to
193/// previously executed transactions.
194#[derive(Clone, Debug, Serialize, Deserialize)]
195pub struct HandleCertificateResponseV1 {
196    pub signed_effects: SignedTransactionEffects,
197    pub events: Option<TransactionEvents>,
198
199    /// If requested, will include all initial versions of objects modified in
200    /// this transaction. This includes owned objects included as input into
201    /// the transaction as well as the assigned versions of shared objects.
202    // TODO: In the future we may want to include shared objects or child objects which were read
203    //  but not modified during execution.
204    pub input_objects: Option<Vec<Object>>,
205
206    /// If requested, will include all changed objects, including mutated,
207    /// created and unwrapped objects. In other words, all objects that
208    /// still exist in the object state after this transaction.
209    pub output_objects: Option<Vec<Object>>,
210    pub auxiliary_data: Option<Vec<u8>>,
211}
212
213#[derive(Clone, Debug, Serialize, Deserialize)]
214pub struct HandleCertificateRequestV1 {
215    pub certificate: CertifiedTransaction,
216
217    pub include_events: bool,
218    pub include_input_objects: bool,
219    pub include_output_objects: bool,
220    pub include_auxiliary_data: bool,
221}
222
223impl HandleCertificateRequestV1 {
224    pub fn new(certificate: CertifiedTransaction) -> Self {
225        Self {
226            certificate,
227            include_events: false,
228            include_input_objects: false,
229            include_output_objects: false,
230            include_auxiliary_data: false,
231        }
232    }
233
234    pub fn with_events(mut self) -> Self {
235        self.include_events = true;
236        self
237    }
238
239    pub fn with_input_objects(mut self) -> Self {
240        self.include_input_objects = true;
241        self
242    }
243
244    pub fn with_output_objects(mut self) -> Self {
245        self.include_output_objects = true;
246        self
247    }
248
249    pub fn with_auxiliary_data(mut self) -> Self {
250        self.include_auxiliary_data = true;
251        self
252    }
253}
254
255/// Response type for the handle Soft Bundle certificates validator API.
256/// If `wait_for_effects` is true, it is guaranteed that:
257///  - Number of responses will be equal to the number of input transactions.
258///  - The order of the responses matches the order of the input transactions.
259///
260/// Otherwise, `responses` will be empty.
261#[derive(Clone, Debug, Serialize, Deserialize)]
262pub struct HandleSoftBundleCertificatesResponseV1 {
263    pub responses: Vec<HandleCertificateResponseV1>,
264}
265
266/// Soft Bundle request.  See [SIP-19](https://github.com/sui-foundation/sips/blob/main/sips/sip-19.md).
267#[derive(Clone, Debug, Serialize, Deserialize)]
268pub struct HandleSoftBundleCertificatesRequestV1 {
269    pub certificates: Vec<CertifiedTransaction>,
270
271    pub wait_for_effects: bool,
272    pub include_events: bool,
273    pub include_input_objects: bool,
274    pub include_output_objects: bool,
275    pub include_auxiliary_data: bool,
276}
277
278#[derive(Clone, Debug, Serialize, Deserialize)]
279pub struct HandleCapabilityNotificationRequestV1 {
280    pub message: SignedAuthorityCapabilitiesV1,
281}
282
283#[derive(Clone, Debug, Serialize, Deserialize)]
284pub struct HandleCapabilityNotificationResponseV1 {
285    // This is needed to make gRPC happy.
286    pub _unused: bool,
287}
iota_types/messages_grpc.rs

iota_types/
messages_grpc.rs
