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

iota_json_rpc_api/
indexer.rs
