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

iota_json_rpc_api/
read.rs
