iota_json_rpc_api/
read.rs

1// Copyright (c) Mysten Labs, Inc.
2// Modifications Copyright (c) 2024 IOTA Stiftung
3// SPDX-License-Identifier: Apache-2.0
4
5use iota_json_rpc_types::{
6    Checkpoint, CheckpointId, CheckpointPage, IotaEvent, IotaGetPastObjectRequest,
7    IotaObjectDataOptions, IotaObjectResponse, IotaPastObjectResponse,
8    IotaTransactionBlockResponse, IotaTransactionBlockResponseOptions, Page,
9    ProtocolConfigResponse,
10    iota_primitives::{Base58 as Base58Schema, ObjectId as ObjectIdSchema, SequenceNumberU64},
11};
12use iota_open_rpc_macros::open_rpc;
13use iota_sdk_types::{ObjectId, TransactionDigest, Version};
14use iota_types::iota_serde::BigInt;
15use jsonrpsee::{core::RpcResult, proc_macros::rpc};
16
17/// Provides methods for reading transaction related data such as transaction
18/// blocks, checkpoints, and protocol configuration. The trait further provides
19/// methods for reading the ledger (current objects) as well its history (past
20/// objects).
21#[open_rpc(namespace = "iota", tag = "Read API")]
22#[rpc(server, client, namespace = "iota")]
23pub trait ReadApi {
24    /// Return if the transaction has been indexed on the fullnode.
25    #[rustfmt::skip]
26    #[method(name = "isTransactionIndexedOnNode")]
27    async fn is_transaction_indexed_on_node(
28        &self,
29        /// the digest of the queried transaction
30        #[schemars(with = "Base58Schema")]
31        digest: TransactionDigest,
32    ) -> RpcResult<bool>;
33
34    /// Return the transaction response object.
35    #[rustfmt::skip]
36    #[method(name = "getTransactionBlock")]
37    async fn get_transaction_block(
38        &self,
39        /// the digest of the queried transaction
40        #[schemars(with = "Base58Schema")]
41        digest: TransactionDigest,
42        /// options for specifying the content to be returned
43        options: Option<IotaTransactionBlockResponseOptions>,
44    ) -> RpcResult<IotaTransactionBlockResponse>;
45
46    /// Returns an ordered list of transaction responses
47    /// The method will throw an error if the input contains any duplicate or
48    /// the input size exceeds QUERY_MAX_RESULT_LIMIT
49    #[rustfmt::skip]
50    #[method(name = "multiGetTransactionBlocks")]
51    async fn multi_get_transaction_blocks(
52        &self,
53        /// A list of transaction digests.
54        #[schemars(with = "Vec<Base58Schema>")]
55        digests: Vec<TransactionDigest>,
56        /// config options to control which fields to fetch
57        options: Option<IotaTransactionBlockResponseOptions>,
58    ) -> RpcResult<Vec<IotaTransactionBlockResponse>>;
59
60    /// Return the object information for a specified object
61    #[rustfmt::skip]
62    #[method(name = "getObject")]
63    async fn get_object(
64        &self,
65        /// the ID of the queried object
66        #[schemars(with = "ObjectIdSchema")]
67        object_id: ObjectId,
68        /// options for specifying the content to be returned
69        options: Option<IotaObjectDataOptions>,
70    ) -> RpcResult<IotaObjectResponse>;
71
72    /// Return the object data for a list of objects
73    #[rustfmt::skip]
74    #[method(name = "multiGetObjects")]
75    async fn multi_get_objects(
76        &self,
77        /// the IDs of the queried objects
78        #[schemars(with = "Vec<ObjectIdSchema>")]
79        object_ids: Vec<ObjectId>,
80        /// options for specifying the content to be returned
81        options: Option<IotaObjectDataOptions>,
82    ) -> RpcResult<Vec<IotaObjectResponse>>;
83
84    /// Note there is no software-level guarantee/SLA that objects with past
85    /// versions can be retrieved by this API, even if the object and version
86    /// exists/existed. The result may vary across nodes depending on their
87    /// pruning policies. Return the object information for a specified version
88    #[rustfmt::skip]
89    #[method(name = "tryGetPastObject")]
90    async fn try_get_past_object(
91        &self,
92        /// the ID of the queried object
93        #[schemars(with = "ObjectIdSchema")]
94        object_id: ObjectId,
95        /// the version of the queried object. If None, default to the latest known version
96        version: SequenceNumberU64,
97        /// options for specifying the content to be returned
98        options: Option<IotaObjectDataOptions>,
99    ) -> RpcResult<IotaPastObjectResponse>;
100
101    /// Note there is no software-level guarantee/SLA that objects with past
102    /// versions can be retrieved by this API, even if the object and
103    /// version exists/existed. The result may vary across nodes depending
104    /// on their pruning policies. Returns the latest object information
105    /// with a version less than or equal to the given version
106    // Note that this endpoint is used by iota replay tool. Also the
107    // implementation in `iota-json-rpc` uses internally the
108    // `AuthorityState::find_object_lt_or_eq_version` method, which has
109    // underlying utility, e.g., `RemoteFetcher::get_child_object` uses
110    // `try_get_object_before_version` to get the object with the versions <=
111    // the given version. We have the `deprecated` flag here to not expose it in
112    // the generated spec file, and it should be only for internal usage.
113    #[method(name = "tryGetObjectBeforeVersion", deprecated = "true")]
114    async fn try_get_object_before_version(
115        &self,
116        /// the ID of the queried object
117        object_id: ObjectId,
118        /// the version of the queried object
119        version: Version,
120    ) -> RpcResult<IotaPastObjectResponse>;
121
122    /// Note there is no software-level guarantee/SLA that objects with past
123    /// versions can be retrieved by this API, even if the object and version
124    /// exists/existed. The result may vary across nodes depending on their
125    /// pruning policies. Return the object information for a specified version
126    #[rustfmt::skip]
127    #[method(name = "tryMultiGetPastObjects")]
128    async fn try_multi_get_past_objects(
129        &self,
130        /// a vector of object and versions to be queried
131        past_objects: Vec<IotaGetPastObjectRequest>,
132        /// options for specifying the content to be returned
133        options: Option<IotaObjectDataOptions>,
134    ) -> RpcResult<Vec<IotaPastObjectResponse>>;
135
136    /// Return a checkpoint
137    #[rustfmt::skip]
138    #[method(name = "getCheckpoint")]
139    async fn get_checkpoint(
140        &self,
141        /// Checkpoint identifier, can use either checkpoint digest, or checkpoint sequence number as input.
142        id: CheckpointId,
143    ) -> RpcResult<Checkpoint>;
144
145    /// Return paginated list of checkpoints
146    #[rustfmt::skip]
147    #[method(name = "getCheckpoints")]
148    #[schemars(with = "Page<Checkpoint, String>")]
149    async fn get_checkpoints(
150        &self,
151        /// An optional paging cursor. If provided, the query will start from the next item after the specified cursor. Default to start from the first item if not specified.
152       #[schemars(with = "Option<String>")]
153       cursor: Option<BigInt<u64>>,
154        /// Maximum item returned per page, default to [QUERY_MAX_RESULT_LIMIT_CHECKPOINTS] if not specified.
155        limit: Option<usize>,
156        /// query result ordering, default to false (ascending order), oldest record first.
157        descending_order: bool,
158    ) -> RpcResult<CheckpointPage>;
159
160    /// Return transaction events.
161    #[method(name = "getEvents")]
162    async fn get_events(
163        &self,
164        /// the event query criteria.
165        #[schemars(with = "Base58Schema")]
166        transaction_digest: TransactionDigest,
167    ) -> RpcResult<Vec<IotaEvent>>;
168
169    /// Return the total number of transaction blocks known to the server.
170    #[method(name = "getTotalTransactionBlocks")]
171    #[schemars(with = "String")]
172    async fn get_total_transaction_blocks(&self) -> RpcResult<BigInt<u64>>;
173
174    /// Return the sequence number of the latest checkpoint that has been
175    /// executed
176    #[method(name = "getLatestCheckpointSequenceNumber")]
177    #[schemars(with = "String")]
178    async fn get_latest_checkpoint_sequence_number(&self) -> RpcResult<BigInt<u64>>;
179
180    /// Return the protocol config table for the given version number.
181    /// If the version number is not specified, If none is specified, the node uses
182    /// the version of the latest epoch it has processed.
183    #[rustfmt::skip]
184    #[method(name = "getProtocolConfig")]
185    async fn get_protocol_config(
186        &self,
187        /// An optional protocol version specifier. If omitted, the latest protocol config table for the node will be returned.
188        #[schemars(with = "Option<String>")]
189        version: Option<BigInt<u64>>,
190    ) -> RpcResult<ProtocolConfigResponse>;
191
192    /// Return the first four bytes of the chain's genesis checkpoint digest.
193    #[method(name = "getChainIdentifier")]
194    async fn get_chain_identifier(&self) -> RpcResult<String>;
195}
iota_json_rpc_api/read.rs

iota_json_rpc_api/
read.rs
