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

iota_types/
messages_grpc.rs
