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