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

iota_json_rpc_api/
indexer.rs
