iota_json_rpc_api/
indexer.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    DynamicFieldPage, EventFilter, EventPage, IotaEvent, IotaNameRecord, IotaObjectDataOptions,
7    IotaObjectResponse, IotaObjectResponseQuery, IotaTransactionBlockEffects,
8    IotaTransactionBlockResponseQuery, IotaTransactionBlockResponseQueryV2, ObjectsPage,
9    TransactionBlocksPage, TransactionFilter,
10};
11use iota_open_rpc_macros::open_rpc;
12use iota_types::{
13    base_types::{IotaAddress, ObjectID},
14    digests::TransactionDigest,
15    dynamic_field::DynamicFieldName,
16    event::EventID,
17};
18use jsonrpsee::{
19    core::{RpcResult, SubscriptionResult},
20    proc_macros::rpc,
21};
22
23/// Provides methods to query transactions, events, or objects and allows to
24/// subscribe to data streams.
25#[open_rpc(namespace = "iotax", tag = "Extended API")]
26#[rpc(server, client, namespace = "iotax")]
27pub trait IndexerApi {
28    /// Return the list of objects owned by an address.
29    /// Note that if the address owns more than `QUERY_MAX_RESULT_LIMIT` objects,
30    /// the pagination is not accurate, because previous page may have been updated
31    /// when the next page is fetched.
32    /// Please use iotax_queryObjects if this is a concern.
33    #[rustfmt::skip]
34    #[method(name = "getOwnedObjects")]
35    async fn get_owned_objects(
36        &self,
37        /// the owner's IOTA address
38        address: IotaAddress,
39        /// the objects query criteria.
40        query: Option<IotaObjectResponseQuery>,
41        /// 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.
42        cursor: Option<ObjectID>,
43        /// Max number of items returned per page, default to [QUERY_MAX_RESULT_LIMIT] if not specified.
44        limit: Option<usize>,
45    ) -> RpcResult<ObjectsPage>;
46
47    /// Return list of transactions for a specified query criteria.
48    #[rustfmt::skip]
49    #[method(name = "queryTransactionBlocks", version <= "1.2.10")]
50    async fn query_transaction_blocks(
51        &self,
52        /// the transaction query criteria.
53        query: IotaTransactionBlockResponseQuery,
54        /// 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.
55        cursor: Option<TransactionDigest>,
56        /// Maximum item returned per page, default to QUERY_MAX_RESULT_LIMIT if not specified.
57        limit: Option<usize>,
58        /// query result ordering, default to false (ascending order), oldest record first.
59        descending_order: Option<bool>,
60    ) -> RpcResult<TransactionBlocksPage>;
61
62    /// Return list of transactions for a specified query criteria.
63    #[rustfmt::skip]
64    #[method(name = "queryTransactionBlocks")]
65    async fn query_transaction_blocks_v2(
66        &self,
67        /// the transaction query criteria.
68        query: IotaTransactionBlockResponseQueryV2,
69        /// 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.
70        cursor: Option<TransactionDigest>,
71        /// Maximum item returned per page, default to QUERY_MAX_RESULT_LIMIT if not specified.
72        limit: Option<usize>,
73        /// query result ordering, default to false (ascending order), oldest record first.
74        descending_order: Option<bool>,
75    ) -> RpcResult<TransactionBlocksPage>;
76
77    /// Return list of events for a specified query criteria.
78    #[rustfmt::skip]
79    #[method(name = "queryEvents")]
80    async fn query_events(
81        &self,
82        /// The event query criteria. See [Event filter](https://docs.iota.org/developer/iota-101/using-events#applying-event-filters) documentation for examples.
83        query: EventFilter,
84        /// optional paging cursor
85        cursor: Option<EventID>,
86        /// maximum number of items per page, default to [QUERY_MAX_RESULT_LIMIT] if not specified.
87        limit: Option<usize>,
88        /// query result ordering, default to false (ascending order), oldest record first.
89        descending_order: Option<bool>,
90    ) -> RpcResult<EventPage>;
91
92    /// Subscribe to a stream of IOTA event
93    #[rustfmt::skip]
94    #[subscription(name = "subscribeEvent", item = IotaEvent)]
95    fn subscribe_event(
96        &self,
97        /// The filter criteria of the event stream. See [Event filter](https://docs.iota.org/developer/iota-101/using-events#applying-event-filters) documentation for examples.
98        filter: EventFilter,
99    ) -> SubscriptionResult;
100
101    /// Subscribe to a stream of IOTA transaction effects
102    #[subscription(name = "subscribeTransaction", item = IotaTransactionBlockEffects)]
103    fn subscribe_transaction(&self, filter: TransactionFilter) -> SubscriptionResult;
104
105    /// Return the list of dynamic field objects owned by an object.
106    #[rustfmt::skip]
107    #[method(name = "getDynamicFields")]
108    async fn get_dynamic_fields(
109        &self,
110        /// The ID of the parent object
111        parent_object_id: ObjectID,
112        /// 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.
113        cursor: Option<ObjectID>,
114        /// Maximum item returned per page, default to [QUERY_MAX_RESULT_LIMIT] if not specified.
115        limit: Option<usize>,
116    ) -> RpcResult<DynamicFieldPage>;
117
118    /// Return the dynamic field object information for a specified object
119    #[rustfmt::skip]
120    #[method(name = "getDynamicFieldObject")]
121    async fn get_dynamic_field_object(
122        &self,
123        /// The ID of the queried parent object
124        parent_object_id: ObjectID,
125        /// The Name of the dynamic field
126        name: DynamicFieldName,
127    ) -> RpcResult<IotaObjectResponse>;
128
129    /// Return the dynamic field object information for a specified object with
130    /// content options.
131    #[rustfmt::skip]
132    #[method(name = "getDynamicFieldObjectV2")]
133    async fn get_dynamic_field_object_v2(
134        &self,
135        /// The ID of the queried parent object
136        parent_object_id: ObjectID,
137        /// The Name of the dynamic field
138        name: DynamicFieldName,
139        /// Options for specifying the content to be returned
140        options: Option<IotaObjectDataOptions>,
141    ) -> RpcResult<IotaObjectResponse>;
142
143    /// Return the resolved record for the given name.
144    #[method(name = "iotaNamesLookup")]
145    async fn iota_names_lookup(
146        &self,
147        /// The name to resolve
148        name: &str,
149    ) -> RpcResult<Option<IotaNameRecord>>;
150
151    /// Return the resolved name for the given address.
152    #[method(name = "iotaNamesReverseLookup")]
153    async fn iota_names_reverse_lookup(
154        &self,
155        /// The address to resolve.
156        address: IotaAddress,
157    ) -> RpcResult<Option<String>>;
158
159    /// Find all registration NFTs for the given address.
160    #[method(name = "iotaNamesFindAllRegistrationNFTs")]
161    async fn iota_names_find_all_registration_nfts(
162        &self,
163        address: IotaAddress,
164        cursor: Option<ObjectID>,
165        limit: Option<usize>,
166        options: Option<IotaObjectDataOptions>,
167    ) -> RpcResult<ObjectsPage>;
168}
iota_json_rpc_api/indexer.rs

iota_json_rpc_api/
indexer.rs
