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

iota_json_rpc_api/
read.rs
