sui_json_rpc_api/
read.rs

1// Copyright (c) Mysten Labs, Inc.
2// SPDX-License-Identifier: Apache-2.0
3
4use jsonrpsee::core::RpcResult;
5use jsonrpsee::proc_macros::rpc;
6
7use sui_json_rpc_types::{
8    Checkpoint, CheckpointId, CheckpointPage, SuiEvent, SuiGetPastObjectRequest,
9    SuiObjectDataOptions, SuiObjectResponse, SuiPastObjectResponse, SuiTransactionBlockResponse,
10    SuiTransactionBlockResponseOptions,
11};
12use sui_json_rpc_types::{ProtocolConfigResponse, ZkLoginIntentScope, ZkLoginVerifyResult};
13use sui_open_rpc_macros::open_rpc;
14use sui_types::base_types::{ObjectID, SequenceNumber, SuiAddress, TransactionDigest};
15use sui_types::sui_serde::BigInt;
16
17#[open_rpc(namespace = "sui", tag = "Read API")]
18#[rpc(server, client, namespace = "sui")]
19pub trait ReadApi {
20    /// Return the transaction response object.
21    #[method(name = "getTransactionBlock")]
22    async fn get_transaction_block(
23        &self,
24        /// the digest of the queried transaction
25        digest: TransactionDigest,
26        /// options for specifying the content to be returned
27        options: Option<SuiTransactionBlockResponseOptions>,
28    ) -> RpcResult<SuiTransactionBlockResponse>;
29
30    /// Returns an ordered list of transaction responses
31    /// The method will throw an error if the input contains any duplicate or
32    /// the input size exceeds QUERY_MAX_RESULT_LIMIT
33    #[method(name = "multiGetTransactionBlocks")]
34    async fn multi_get_transaction_blocks(
35        &self,
36        /// A list of transaction digests.
37        digests: Vec<TransactionDigest>,
38        /// config options to control which fields to fetch
39        options: Option<SuiTransactionBlockResponseOptions>,
40    ) -> RpcResult<Vec<SuiTransactionBlockResponse>>;
41
42    /// Return the object information for a specified object
43    #[method(name = "getObject")]
44    async fn get_object(
45        &self,
46        /// the ID of the queried object
47        object_id: ObjectID,
48        /// options for specifying the content to be returned
49        options: Option<SuiObjectDataOptions>,
50    ) -> RpcResult<SuiObjectResponse>;
51
52    /// Return the object data for a list of objects
53    #[method(name = "multiGetObjects")]
54    async fn multi_get_objects(
55        &self,
56        /// the IDs of the queried objects
57        object_ids: Vec<ObjectID>,
58        /// options for specifying the content to be returned
59        options: Option<SuiObjectDataOptions>,
60    ) -> RpcResult<Vec<SuiObjectResponse>>;
61
62    /// Note there is no software-level guarantee/SLA that objects with past versions
63    /// can be retrieved by this API, even if the object and version exists/existed.
64    /// The result may vary across nodes depending on their pruning policies.
65    /// Return the object information for a specified version
66    #[method(name = "tryGetPastObject")]
67    async fn try_get_past_object(
68        &self,
69        /// the ID of the queried object
70        object_id: ObjectID,
71        /// the version of the queried object. If None, default to the latest known version
72        version: SequenceNumber,
73        /// options for specifying the content to be returned
74        options: Option<SuiObjectDataOptions>,
75    ) -> RpcResult<SuiPastObjectResponse>;
76
77    /// Note there is no software-level guarantee/SLA that objects with past versions
78    /// can be retrieved by this API, even if the object and version exists/existed.
79    /// The result may vary across nodes depending on their pruning policies.
80    /// Returns the latest object information with a version less than or equal to the given version
81    #[method(name = "tryGetObjectBeforeVersion", deprecated = "true")]
82    async fn try_get_object_before_version(
83        &self,
84        /// the ID of the queried object
85        object_id: ObjectID,
86        /// the version of the queried object
87        version: SequenceNumber,
88    ) -> RpcResult<SuiPastObjectResponse>;
89
90    /// Note there is no software-level guarantee/SLA that objects with past versions
91    /// can be retrieved by this API, even if the object and version exists/existed.
92    /// The result may vary across nodes depending on their pruning policies.
93    /// Return the object information for a specified version
94    #[method(name = "tryMultiGetPastObjects")]
95    async fn try_multi_get_past_objects(
96        &self,
97        /// a vector of object and versions to be queried
98        past_objects: Vec<SuiGetPastObjectRequest>,
99        /// options for specifying the content to be returned
100        options: Option<SuiObjectDataOptions>,
101    ) -> RpcResult<Vec<SuiPastObjectResponse>>;
102
103    /// Return a checkpoint
104    #[method(name = "getCheckpoint")]
105    async fn get_checkpoint(
106        &self,
107        /// Checkpoint identifier, can use either checkpoint digest, or checkpoint sequence number as input.
108        id: CheckpointId,
109    ) -> RpcResult<Checkpoint>;
110
111    /// Return paginated list of checkpoints
112    #[method(name = "getCheckpoints")]
113    async fn get_checkpoints(
114        &self,
115        /// 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.
116        cursor: Option<BigInt<u64>>,
117        /// Maximum item returned per page, default to [QUERY_MAX_RESULT_LIMIT_CHECKPOINTS] if not specified.
118        limit: Option<usize>,
119        /// query result ordering, default to false (ascending order), oldest record first.
120        descending_order: bool,
121    ) -> RpcResult<CheckpointPage>;
122
123    /// Return transaction events.
124    #[method(name = "getEvents")]
125    async fn get_events(
126        &self,
127        /// the event query criteria.
128        transaction_digest: TransactionDigest,
129    ) -> RpcResult<Vec<SuiEvent>>;
130
131    /// Return the total number of transaction blocks known to the server.
132    #[method(name = "getTotalTransactionBlocks")]
133    async fn get_total_transaction_blocks(&self) -> RpcResult<BigInt<u64>>;
134
135    /// Return the sequence number of the latest checkpoint that has been executed
136    #[method(name = "getLatestCheckpointSequenceNumber")]
137    async fn get_latest_checkpoint_sequence_number(&self) -> RpcResult<BigInt<u64>>;
138
139    /// Return the protocol config table for the given version number.
140    /// If the version number is not specified, If none is specified, the node uses the version of the latest epoch it has processed.
141    #[method(name = "getProtocolConfig")]
142    async fn get_protocol_config(
143        &self,
144        /// An optional protocol version specifier. If omitted, the latest protocol config table for the node will be returned.
145        version: Option<BigInt<u64>>,
146    ) -> RpcResult<ProtocolConfigResponse>;
147
148    /// Return the first four bytes of the chain's genesis checkpoint digest.
149    #[method(name = "getChainIdentifier")]
150    async fn get_chain_identifier(&self) -> RpcResult<String>;
151
152    /// Verify a zklogin signature for the given bytes, intent scope and author.
153    #[method(name = "verifyZkLoginSignature")]
154    async fn verify_zklogin_signature(
155        &self,
156        /// The Base64 string of bcs bytes for raw transaction data or personal message indicated by intent_scope.
157        bytes: String,
158        /// The Base64 string of the zklogin signature to verify.
159        signature: String,
160        /// The intent scope, either transaction data or personal message. Used to parse bytes.
161        intent_scope: ZkLoginIntentScope,
162        /// The author of the signature.
163        author: SuiAddress,
164    ) -> RpcResult<ZkLoginVerifyResult>;
165}
sui_json_rpc_api/read.rs

sui_json_rpc_api/
read.rs
